OXYGENHUB
# b6dfcb61cf5e oxygenhub / docs / keyless.md
8.7 KiB · Markdown · last changed Agent grants: agents act for their owner with no key (keyless step 5) 18 days ago renderedsource blame history raw
1 
# Keyless signing: short-lived keys from an OIDC identity
2
3 
Design for oxygenhub#241, written 2026-10-17. **Status: accepted** (Andy,
4 
2026-10-17, the four decisions below as recommended). Built on 2026-10-17:
5 
steps 1 to 5 of the order of work and the hub's acceptance attestation
6 
(step 6's first half, Oxygen spec §14.7); the log's time is next. Agents'
7 
grants are signed by their owner's key (Andy's choice, 2026-10-17), so a
8 
certified key's changes count in the owner's name without trusting the
9 
hub for authorship. It builds on the hub's
10 
OIDC issuer (hub spec §13.5) and on the transparency log
11 
(docs/transparency.md, #238/#240).
12
13 
## Why
14
15 
Every signing key in Oxygen lives long: a runner's `runner.key`, an
16 
agent's key in its home (`~/.oxy-agents/claude/keys`), a person's key. A
17 
delegation can already expire in minutes (`oxy identity delegate add
18 
--expires 30m`), but the key it names stays on disk afterwards, and each
19 
grant re-issues the owner's identity by hand. A stolen key works until
20 
someone notices and revokes it.
21
22 
Sigstore's answer (Fulcio) is a key that lives only for one job: the
23 
signer proves who it is with an OIDC token, gets a certificate for a fresh
24 
key valid for minutes, signs, and throws the key away. Nothing long-lived
25 
sits on the runner or in the agent's home, and a policy can name **who**
26 
may sign ("this pipeline on main", "Claude, for andymccall") rather than
27 
which key.
28
29 
## What exists already
30
31 
- **Delegation** (spec §14.2, §14.5): an identity lists delegates with a
32 
  scope (`changes`, `refs`, `seal`, `all`) and an expiry, checked against
33 
  the time the signed object claims. The identity issues it itself; no
34 
  other key can.
35 
- **The hub's OIDC issuer** (hub spec §13.5, `oidc.rs`): a Flow job that
36 
  declares `identity "AUD"` gets an RS256 token with `sub`
37 
  `repo:OWNER/NAME:bookmark:B`, the environment and its approval, expiring
38 
  with the job (at most 6 h). The JWKS is at `/.well-known/jwks.json`.
39 
  The hub already uses these tokens for keyless backups to GCS and S3.
40 
- **The hub's key** (hub spec §15.5) signs web edits, wiki changes,
41 
  Diffusion bumps, swarm tickets and SLSA provenance.
42
43 
What is missing is a delegation **issued by someone else** (a certificate
44 
authority), policy rules that name identities rather than keys, and time
45 
a verifier can trust once the certificate has long expired.
46
47 
## The certificate
48
49 
A new object, `certificate`, issued and signed by a hub's key (its
50 
composite Ed25519 + ML-DSA-65 key, so certificates stay post-quantum):
51
52 
```
53 
Certificate {
54 
  version     [0]: 1
55 
  key         [1]: Identity        // the fresh key pair's public identity
56 
  issuer      [2]: KeyId           // the hub key that signs it
57 
  subject     [3]: text            // who proved it: "repo:andymccall/oxygen:bookmark:main", "agent:claude@andymccall"
58 
  claims      [4]: map text->text  // what else the token said: environment, approval, run, job
59 
  scope       [5]: Scope           // changes, refs, seal
60 
  not_before  [6]: u64             // milliseconds
61 
  expires     [7]: u64             // not_before + at most 10 minutes for jobs
62 
}
63 
```
64
65 
It travels with what it signed, like an identity: a push carries the
66 
certificates of the keys that signed its changes and attestations, and a
67 
fetch brings them.
68
69 
## Getting one
70
71 
```
72 
POST /api/v1/keyless/certify
73 
  { "token": "<OIDC token>", "identity": "<fresh identity, CBOR, base64>",
74 
    "proof": "<the fresh key's signature over the hub's challenge>", "scope": "refs" }
75 
→ { "certificate": "<CBOR, base64>" }
76 
```
77
78 
The hub checks:
79 
- the token: its own issuer to begin with (others later, see the
80 
  decisions);
81 
- that the proof shows the caller holds the fresh key (the challenge
82 
  signatures of spec §14.3);
83 
- that the scope asked is one the subject may have.
84
85 
It then signs a certificate expiring at the earlier of ten minutes and
86 
the token's expiry, and logs it (below).
87
88 
- **A Flow job** gets a token as it does today, generates a key in memory,
89 
  certifies it, signs (a receipt, a tag, an attestation of a release), and
90 
  the key dies with the job. `runner.key` remains only to authenticate the
91 
  runner to the hub, not to sign what jobs made.
92 
- **An agent** has no OIDC token of its own. The hub gives it one when its
93 
  owner says so: `oh agent grant claude --scope changes --for 8h` on
94 
  Andy's side, or a hub page with a button, makes an agent token. The
95 
  agent exchanges that token for certificates as it needs them (each ten
96 
  minutes). The owner revokes the grant on the hub, and no key is left
97 
  anywhere. The agent's home holds only the grant token, which signs
98 
  nothing by itself.
99 
- **People** keep their own keys; passkeys (#237) are the separate answer
100 
  for them.
101
102 
## Policy names identities
103
104 
A rule today lists keys. It may also list **subjects from an issuer**:
105
106 
```
107 
rule "main" {
108 
  key 4cd9916c…                                   // Andy, as today
109 
  subject "repo:andymccall/oxygen:bookmark:main" issuer HUB scope refs
110 
  subject "agent:claude@andymccall" issuer HUB scope changes
111 
}
112 
```
113
114 
`HUB` is the hub key's KeyId, so the policy says which CA it trusts for
115 
which subjects. A pattern may end in `*`. The policy's roots still sign
116 
the policy, as now.
117
118 
## Verifying later
119
120 
A certificate is valid for ten minutes. A verifier checking a signature a
121 
year later must know **the signature was made inside those ten minutes**,
122 
and the signer's own claim of time is not enough (that is #240's
123 
problem). Two sources, in order of strength:
124
125 
1. **The transparency log** (docs/transparency.md): the hub logs every
126 
   certificate it issues and every object signed by a certified key. An
127 
   object integrated (witnessed) before its certificate's `expires` was
128 
   signed in time. This is exactly how Sigstore uses Rekor with Fulcio.
129 
2. **The hub's acceptance**, until the log exists: when a push carries a
130 
   certified signature, the hub countersigns its acceptance time on the
131 
   object (a small attestation, kind `accepted`). That trusts the hub's
132 
   clock alone, which the log later removes. Built: the hub signs one with
133 
   its key for each reference attestation by a key it certified, keeps
134 
   it beside the attestation and serves it with the bookmark; a fetch
135 
   uses its time only when the certificate's issuer signed it for exactly
136 
   that attestation.
137
138 
A signature whose certificate has expired, with neither proof, is
139 
invalid.
140
141 
## Revocation
142
143 
Short certificates mostly replace revocation: a stolen key is useless ten
144 
minutes later. What can still be revoked:
145 
- **the grant** an agent holds (on the hub, at once);
146 
- **the issuer** itself (a policy without the hub's key trusts none of
147 
  its certificates);
148 
- **one certificate** by its hash (a revocation listed in the policy, as
149 
  keys are now), for the ten minutes it matters.
150
151 
## Order of work
152
153 
1. **The certificate object** in oxy-core: encoding, verification (issuer
154 
   signature, scope, expiry against a given trusted time), carried in
155 
   bundles like identities. Spec §14. About three days.
156 
2. **The certify endpoint** on the hub: token check, proof of
157 
   possession, issuing, logging. About two days.
158 
3. **Flow jobs:** the runner certifies a fresh key per job and signs
159 
   receipts with it; the hub checks receipts by certificate as well as by
160 
   `flow_runner_keys`. About two days.
161 
4. **Policy subjects:** rules naming issuers and subject patterns; `oxy
162 
   policy grant --subject`. About two days.
163 
5. **Agent grants:** `oh agent grant`, the hub's grant tokens, and oxy
164 
   certifying on demand when `author.signer` is `keyless`. About three days.
165 
6. **Trusted time:** the acceptance attestation now; the log's integrated
166 
   time when #238 lands.
167
168 
## Decisions (taken 2026-10-17)
169
170 
Andy chose the recommendation each time: our own composite-signed
171 
certificate, built now with the hub's acceptance time (the log's time
172 
later), agent grants that retire the agent keys, and the hub's own OIDC
173 
issuer first.
174
175 
1. **Certificate format:**
176 
   - Our own CBOR object, composite-signed: post-quantum, and small.
177 
   - X.509, as Fulcio issues: readable by Sigstore's tools, but classical
178 
     only.
179 
   - Recommendation: **our own**, with an X.509 export later if a
180 
     customer needs Sigstore's tools to read them.
181 
2. **Build before or after the transparency log?** Certificates are only
182 
   as good as the proof of when they were used.
183 
   - Recommendation: **build steps 1 to 4 now with the hub's acceptance
184 
     attestation**, and move to the log's time when #238 step 1 lands.
185 
3. **Agents:** a grant on the hub that the agent exchanges for ten-minute
186 
   certificates, replacing the long-lived agent keys and the 8 h
187 
   delegations re-issued by hand.
188 
   - Recommendation: **yes**, and retire `~/.oxy-agents/*/keys` once it
189 
     works.
190 
4. **Other OIDC issuers** (GitHub Actions, GitLab CI, Google service
191 
   accounts) as subjects, for repositories mirrored or built elsewhere:
192 
   - Recommendation: **the hub's own issuer first**; others as a site
193 
     setting listing trusted issuers, later.