# Federation authentication and trust

Use TLS 1.3 plus a pinned publisher signing key. TLS authenticates the configured host and protects credentials/data in transit. The Ed25519 key authenticates exported views, independent of a particular connection. A verified identity still needs a current Share grant. There is no automatic trust on first use or credential forwarding to a link in a document.

## Personal pairing with mTLS

Provision a server certificate for the owner's hostname and a client certificate with Client Authentication usage from a trusted CA. On the owner, set `server.mtls.client_ca` and map the **base64url, unpadded SHA-256 of the leaf DER** to an operator-named principal:

```yaml
server:
  mtls:
    client_ca: private/peer-ca.pem
    required: false
    principals:
      - principal: bob-peer
        certificate_sha256: replace-with-verified-leaf-fingerprint
```

Add `certificate` and `private_key` under Bob's peer config. Do not also configure a bearer token for certificate-only pairing. A certificate alone receives the federation capability, never ordinary catalog or admin access. In Alice's `federation.grants`, bind the same principal and optionally the same leaf fingerprint. `required: true` requires a valid client certificate for every TLS connection, including administrators. The service uses verified TLS connection state; forwarded certificate or user headers confer no identity.

## OAuth workload access

Use an enrolled self-hosted issuer. The server supports JWT access tokens of type `at+jwt` and optional opaque-token introspection. It validates signature, issuer, audience, allowed algorithm, validity times and explicit principal/scope rules. It identifies the subject by issuer and subject, and optionally matches `client_id`. Role claims are not capabilities. OAuth mappings for whole-bundle administration need an explicit subject and whole-bundle prefix. Use a separate rule and credential for each workload.

```yaml
server:
  oauth:
    resource: https://alice.example.invalid
    jwks_cache_secs: 60
    issuers:
      - issuer: https://identity.example.invalid
        jwks_url: https://identity.example.invalid/keys
        audience: https://alice.example.invalid
        algorithms: [ES256, RS256]
        rules:
          - principal: bob-peer
            subject: bob-workload
            client_id: bob-knowledge
            scopes: [knowledge:share]
            capabilities: [federation]
            prefixes: []
            proof: mtls
```

In Bob's peer entry, configure `oauth.token_endpoint`, `client_id`, `resource`, `scopes` and optionally `client_secret_env`. Use `certificate` and `private_key` for mTLS client authentication and certificate-bound tokens. For `proof: dpop`, set an operator-provisioned `dpop_private_key` PEM and `dpop_public_jwk` on the OAuth client. The issuer must bind the issued access token to that key. The server verifies method, canonical URI, token hash, timestamp and replay ID. The resource base URI must match the public endpoint for DPoP. For bearer tokens without sender binding, use `proof: none`. OAuth introspection is opt-in on one issuer per server, uses an enrolled endpoint, and does not cache active token decisions. Supply one of `client_secret_env` or an owner-private `client_secret_file`. OAuth access-token expiry caps the authorization lease. Key discovery is bounded and uses configured endpoints or same-origin issuer discovery. There are no token-service redirects.

OAuth client credentials are cached briefly until expiry. The Rust `oauth::client_token` helper also supports explicit access-token exchange for a named resource; a user's token is never silently forwarded or exchanged as part of ordinary federation. Grant revocation and issuer offboarding are separate. Grant changes take effect at the owner even while an OAuth token is valid. For JWT identity revocation use short expirations or provider introspection. DPoP server nonce negotiation is outside this profile.

## Human OIDC sign-in

Register a native application with the issuer and loopback callback. Configure a named profile under `server.oauth.login`. For example:

```yaml
server:
  oauth:
    login:
      lab-cli:
        issuer: https://identity.example.invalid
        authorization_endpoint: https://identity.example.invalid/authorize
        token_endpoint: https://identity.example.invalid/token
        jwks_url: https://identity.example.invalid/keys
        client_id: knowledge-cli
        resource: https://alice.example.invalid
        redirect_uri: http://127.0.0.1:8123/callback
        scopes: [knowledge:share]
```

Run `knowledge -c <config> federation login lab-cli --token-file private/lab-access.token`. Open the printed URL in a browser. The CLI listens only on the literal loopback address, validates callback state and S256 PKCE, and verifies the ID token's issuer, audience, nonce, signature and lifetime. It writes only the access token to a new private file. The ID token is never used as a Knowledge API credential. Local and gateway authorization still uses the server's configured OAuth rule and the grant. `oidc::Login` supports host-managed callbacks when embedding the library.

## Operational boundaries

- Pin issuer endpoints and the publisher key independently. A rotation needs explicit re-enrollment; keep certificates, token credentials, database keys and publisher keys separate. File-based private keys need owner-only permissions on Unix.
- Peer requests use operator-enrolled endpoints, no redirects and no implicit proxies. Share manifests contain exact signed payload bytes, not trusted instructions. An archive or evidence locator never chooses a network destination.
- A consumer sees only its configured aliases. A Share request sees only its scoped evidence and opaque change cursor. `304 Not Modified` is evaluated after authorization. Replicated content and derivations are encrypted on disk; the original OKF source, intentional exports and local key files need filesystem protection.
- A lost connection does not prove revocation. Default offline time is zero. A known denial closes serving immediately; a previously granted finite offline interval may permit cooperative continued use when the owner is unreachable. Already disclosed plaintext cannot be revoked by a protocol.

Primary standards: [OAuth Security BCP](https://www.rfc-editor.org/rfc/rfc9700.html), [JWT access tokens](https://www.rfc-editor.org/rfc/rfc9068.html), [mTLS-bound tokens](https://www.rfc-editor.org/rfc/rfc8705.html), [DPoP](https://www.rfc-editor.org/rfc/rfc9449.html), [OIDC Core](https://openid.net/specs/openid-connect-core-1_0.html), [OAuth for Native Apps](https://www.rfc-editor.org/rfc/rfc8252.html), [protected resource metadata](https://www.rfc-editor.org/rfc/rfc9728.html).
