docs/keyless.md: short-lived keys from an OIDC identity, proposed 52ae6422e5a1

# Keyless signing: short-lived keys from an OIDC identity

Design for oxygenhub#241, written 2026-10-17. **Status: proposed.** Nothing

here is built yet; it is for Andy to read and decide. It builds on the hub's

OIDC issuer (hub spec §13.5) and on the transparency log

(docs/transparency.md, #238/#240).

## Why

Every signing key in Oxygen lives long: a runner's `runner.key`, an

agent's key in its home (`~/.oxy-agents/claude/keys`), a person's key. A

delegation can already expire in minutes (`oxy identity delegate add

--expires 30m`), but the key it names stays on disk afterwards, and each

grant re-issues the owner's identity by hand. A stolen key works until

someone notices and revokes it.

Sigstore's answer (Fulcio) is a key that lives only for one job: the

signer proves who it is with an OIDC token, gets a certificate for a fresh

key valid for minutes, signs, and throws the key away. Nothing long-lived

sits on the runner or in the agent's home, and a policy can name **who**

may sign ("this pipeline on main", "Claude, for andymccall") rather than

which key.

## What exists already

- **Delegation** (spec §14.2, §14.5): an identity lists delegates with a

  scope (`changes`, `refs`, `seal`, `all`) and an expiry, checked against

  the time the signed object claims. The identity issues it itself; no

  other key can.

- **The hub's OIDC issuer** (hub spec §13.5, `oidc.rs`): a Flow job that

  declares `identity "AUD"` gets an RS256 token with `sub`

  `repo:OWNER/NAME:bookmark:B`, the environment and its approval, expiring

  with the job (at most 6 h). The JWKS is at `/.well-known/jwks.json`.

  The hub already uses these tokens for keyless backups to GCS and S3.

- **The hub's key** (hub spec §15.5) signs web edits, wiki changes,

  Diffusion bumps, swarm tickets and SLSA provenance.

What is missing is a delegation **issued by someone else** (a certificate

authority), policy rules that name identities rather than keys, and time

a verifier can trust once the certificate has long expired.

## The certificate

A new object, `certificate`, issued and signed by a hub's key (its

composite Ed25519 + ML-DSA-65 key, so certificates stay post-quantum):

```

Certificate {

  version     [0]: 1

  key         [1]: Identity        // the fresh key pair's public identity

  issuer      [2]: KeyId           // the hub key that signs it

  subject     [3]: text            // who proved it: "repo:andymccall/oxygen:bookmark:main", "agent:claude@andymccall"

  claims      [4]: map text->text  // what else the token said: environment, approval, run, job

  scope       [5]: Scope           // changes, refs, seal

  not_before  [6]: u64             // milliseconds

  expires     [7]: u64             // not_before + at most 10 minutes for jobs

}

```

It travels with what it signed, like an identity: a push carries the

certificates of the keys that signed its changes and attestations, and a

fetch brings them.

## Getting one

```

POST /api/v1/keyless/certify

  { "token": "<OIDC token>", "identity": "<fresh identity, CBOR, base64>",

    "proof": "<the fresh key's signature over the hub's challenge>", "scope": "refs" }

→ { "certificate": "<CBOR, base64>" }

```

The hub checks:

- the token: its own issuer to begin with (others later, see the

  decisions);

- that the proof shows the caller holds the fresh key (the challenge

  signatures of spec §14.3);

- that the scope asked is one the subject may have.

It then signs a certificate expiring at the earlier of ten minutes and

the token's expiry, and logs it (below).

- **A Flow job** gets a token as it does today, generates a key in memory,

  certifies it, signs (a receipt, a tag, an attestation of a release), and

  the key dies with the job. `runner.key` remains only to authenticate the

  runner to the hub, not to sign what jobs made.

- **An agent** has no OIDC token of its own. The hub gives it one when its

  owner says so: `oh agent grant claude --scope changes --for 8h` on

  Andy's side, or a hub page with a button, makes an agent token. The

  agent exchanges that token for certificates as it needs them (each ten

  minutes). The owner revokes the grant on the hub, and no key is left

  anywhere. The agent's home holds only the grant token, which signs

  nothing by itself.

- **People** keep their own keys; passkeys (#237) are the separate answer

  for them.

## Policy names identities

A rule today lists keys. It may also list **subjects from an issuer**:

```

rule "main" {

  key 4cd9916c…                                   // Andy, as today

  subject "repo:andymccall/oxygen:bookmark:main" issuer HUB scope refs

  subject "agent:claude@andymccall" issuer HUB scope changes

}

```

`HUB` is the hub key's KeyId, so the policy says which CA it trusts for

which subjects. A pattern may end in `*`. The policy's roots still sign

the policy, as now.

## Verifying later

A certificate is valid for ten minutes. A verifier checking a signature a

year later must know **the signature was made inside those ten minutes**,

and the signer's own claim of time is not enough (that is #240's

problem). Two sources, in order of strength:

1. **The transparency log** (docs/transparency.md): the hub logs every

   certificate it issues and every object signed by a certified key. An

   object integrated (witnessed) before its certificate's `expires` was

   signed in time. This is exactly how Sigstore uses Rekor with Fulcio.

2. **The hub's acceptance**, until the log exists: when a push carries a

   certified signature, the hub countersigns its acceptance time on the

   object (a small attestation, kind `accepted`). That trusts the hub's

   clock alone, which the log later removes.

A signature whose certificate has expired, with neither proof, is

invalid.

## Revocation

Short certificates mostly replace revocation: a stolen key is useless ten

minutes later. What can still be revoked:

- **the grant** an agent holds (on the hub, at once);

- **the issuer** itself (a policy without the hub's key trusts none of

  its certificates);

- **one certificate** by its hash (a revocation listed in the policy, as

  keys are now), for the ten minutes it matters.

## Order of work

1. **The certificate object** in oxy-core: encoding, verification (issuer

   signature, scope, expiry against a given trusted time), carried in

   bundles like identities. Spec §14. About three days.

2. **The certify endpoint** on the hub: token check, proof of

   possession, issuing, logging. About two days.

3. **Flow jobs:** the runner certifies a fresh key per job and signs

   receipts with it; the hub checks receipts by certificate as well as by

   `flow_runner_keys`. About two days.

4. **Policy subjects:** rules naming issuers and subject patterns; `oxy

   policy grant --subject`. About two days.

5. **Agent grants:** `oh agent grant`, the hub's grant tokens, and oxy

   certifying on demand when `author.signer` is `keyless`. About three days.

6. **Trusted time:** the acceptance attestation now; the log's integrated

   time when #238 lands.

## Decisions for Andy

1. **Certificate format:**

   - Our own CBOR object, composite-signed: post-quantum, and small.

   - X.509, as Fulcio issues: readable by Sigstore's tools, but classical

     only.

   - Recommendation: **our own**, with an X.509 export later if a

     customer needs Sigstore's tools to read them.

2. **Build before or after the transparency log?** Certificates are only

   as good as the proof of when they were used.

   - Recommendation: **build steps 1 to 4 now with the hub's acceptance

     attestation**, and move to the log's time when #238 step 1 lands.

3. **Agents:** a grant on the hub that the agent exchanges for ten-minute

   certificates, replacing the long-lived agent keys and the 8 h

   delegations re-issued by hand.

   - Recommendation: **yes**, and retire `~/.oxy-agents/*/keys` once it

     works.

4. **Other OIDC issuers** (GitHub Actions, GitLab CI, Google service

   accounts) as subjects, for repositories mirrored or built elsewhere:

   - Recommendation: **the hub's own issuer first**; others as a site

     setting listing trusted issuers, later.