@metalabel/dfos-client 0.35.0 → 0.36.1

package/README.md

@@ -136,7 +136,7 @@ It throws `ApiRequestVerifyError`, carrying `reason` (`invalid` / `unverifiable`
 
 ### `@metalabel/dfos-client/siwd`
 
-The end-to-end integration recipe (mint an app identity, serve the app description, verify the callback) is at <https://docs.dfos.com/docs/developers/sign-in-with-dfos/setup>.
+There are two end-to-end integration recipes, and which one you want depends on where your application runs. An app with a domain (mint an app identity, serve the app description, verify the callback) follows <https://docs.dfos.com/docs/developers/sign-in-with-dfos/setup>. A CLI or agent running on the user's own machine, redirecting to a loopback port, follows <https://docs.dfos.com/docs/developers/sign-in-with-dfos/local-apps>.
 
 ```typescript
 import {
@@ -172,7 +172,54 @@ await verifySiwd(client, jws, {
 
 `consumeNonce` returns true iff **this** verifier minted the nonce and it was unspent — membership in verifier-minted state is what satisfies the spec's rule that the verifier MUST have minted the nonce it checks, and deleting it in the same operation is what makes it single-use. The atomicity is the caller's: a get-then-delete lets two concurrent replays both win, where a Redis `GETDEL` or a `DELETE … RETURNING` does not. Under either discipline the nonce check runs at most once, and only after every other check has passed, so an invalid presentation can never burn a nonce the user is still holding.
 
-`createSiwdLoginRequest` throws rather than returning an error on the two things that are RP misconfiguration: an `authorizeUrl` or `redirectUri` that is not an absolute URL, and any scope other than `identity` over a loopback redirect (a local port holds no `client_did` for a credential to be issued to — see [SIWD.md](../../specs/SIWD.md)).
+`createSiwdLoginRequest` throws rather than returning an error on the two things that are RP misconfiguration: an `authorizeUrl` or `redirectUri` that is not an absolute URL, and any scope other than `identity` over a loopback redirect that names no client identity.
+
+**Loopback redirects** — `http://localhost`, `http://127.0.0.1`, or `http://[::1]`, on any port — come in two shapes. The **anonymous** one is unchanged: no `client_did`, `scope=identity` only, and the consent screen shows the local delivery target and nothing else. The **key-proven** one is the [loopback credential tier](../../specs/SIWD.md#loopback-clients): the request carries a `client_did`, an ask proof over its own challenge bytes, and — unless the DID is already resident on the host — the client's identity chain. That is what lets local software receive a credential. It cannot prove where it came from, but it can prove it controls the keys, and the host's consent screen says exactly that. Credentials minted this way come back in the URL **fragment** and carry a hard expiry ceiling the host enforces; 14 days is the spec's recommendation.
+
+The fragment is what keeps the credential off every server, and it is also why a CLI needs one extra step: a browser does not send the fragment to your loopback listener either, so the request line your local server sees carries the query and nothing else. Answer it with a small page whose script reads `location.href` and posts the whole URL back to your server, then feed _that_ to `readSiwdCallback`. A browser relying party just passes `location.href`.
+
+```typescript
+import {
+  createSiwdLoopbackLoginRequest,
+  mintSiwdClientIdentity,
+  restoreSiwdClientIdentity,
+} from '@metalabel/dfos-client/siwd';
+
+// The one place this kit generates a key. Persist `privateKey` + `chain` and
+// restore them next run: a client that re-mints is a NEW did, so it re-consents
+// every time and orphans the credentials the last run earned.
+const app = saved
+  ? await restoreSiwdClientIdentity(saved) // { privateKey, chain }
+  : await mintSiwdClientIdentity();
+
+const request = await createSiwdLoopbackLoginRequest({
+  authorizeUrl: 'https://app.example.com/authorize',
+  redirectUri: 'http://127.0.0.1:8976/callback',
+  scope: 'read:profile',
+  client: app, // did + kid + signer, and the chain to carry
+});
+// open request.url, hold request.expect.nonce in memory, and read back the FULL
+// callback URL (see above — location.search alone would miss the credential).
+const result = readSiwdCallback(callbackUrl);
+if (result.kind === 'success') {
+  // Consumed verification, store of size one: a credential-returning scope
+  // requires it, and one outstanding nonce in memory IS the store. `client` is
+  // the resolver from the setup section, not the identity above.
+  let outstanding: string | undefined = request.expect.nonce;
+  const session = await verifySiwd(client, result.jws, {
+    domain: request.expect.domain,
+    consumeNonce: (nonce) => {
+      if (outstanding === undefined || nonce !== outstanding) return false;
+      outstanding = undefined;
+      return true;
+    },
+  });
+  if (session.ok) {
+    // only now is result.credential a credential you earned — store it, and
+    // send a per-request proof signed by app.signer when you spend it
+  }
+}
+```
 
 `siwdSigningInput(challenge)` is the pure byte contract both the signer and the verifier share (see [SIWD.md](../../specs/SIWD.md)); `createSiwdChallenge` mints a challenge on its own for a caller building its own redirect; `verifySiwd` is a no-throw verifier that accepts only a current `authKeys` entry of a non-deleted identity.
 

package/dist/siwd.d.ts

@@ -9,6 +9,19 @@ import '@metalabel/dfos-web-relay/peer-client';
  * routing dispatchers tell a SIWD proof apart from credentials and chain ops.
  */
 declare const SIWD_JWS_TYP = "did:dfos:siwd";
+/**
+ * The normative JWS header `typ` for a client ASK PROOF — the artifact a
+ * loopback client signs to prove key control at ask-time, registered alongside
+ * `SIWD_JWS_TYP` by SIWD.md §The ask proof.
+ *
+ * The two artifacts cover the SAME canonical challenge bytes, so the distinct
+ * `typ` is the only thing keeping them from being fungible: without it, an ask
+ * proof a client signed to open a consent screen would present as a subject's
+ * sign-in for that same challenge, and a subject's sign-in would present as a
+ * client's ask. The typ gate on each side is what scopes a signature to the
+ * purpose it was produced for.
+ */
+declare const SIWD_ASK_JWS_TYP = "did:dfos:siwd-ask";
 interface SiwdChallenge {
     /** Origin domain of the requesting application. */
     domain: string;
@@ -74,7 +87,13 @@ interface SiwdLoginRequestInput {
     domain: string;
     /** Exact redirect target; must match the RP's registered or served allowlist. */
     redirectUri: string;
-    /** Requested scope. `identity` is the only scope implemented today. */
+    /**
+     * Requested scope: a space-separated SET of scope tokens (the OAuth `scope`
+     * convention), each of which must be one specs/SIWD.md §Scopes and Credentials
+     * registers. A request naming an unregistered token is refused WHOLE rather
+     * than partially honored — a consent screen that silently dropped a token
+     * would describe something other than what was asked for.
+     */
     scope: string;
     /** Consent-screen prose. A host MAY decline to render it; see specs/SIWD.md. */
     statement?: string;
@@ -86,7 +105,11 @@ interface SiwdLoginRequestInput {
      * only the signature would accept it.
      */
     did?: string;
-    /** The RP's own DID. Omitted from the URL automatically for loopback redirects. */
+    /**
+     * The RP's own DID. Rides through on a loopback redirect too, but a host
+     * honors it there only under the loopback credential tier — see
+     * `createSiwdLoopbackLoginRequest`, which adds the proof that backs it.
+     */
     clientDid?: string;
     /** Supply a nonce minted elsewhere (e.g. by your backend); default: minted here. */
     nonce?: string;
@@ -132,32 +155,219 @@ interface SiwdLoginRequest {
  * OUTBOUND half of profile A. `readSiwdCallback` is the inbound half, and
  * `verifySiwd` is what both compose around: mint → redirect, read → verify.
  *
- * The rule this function exists to own is the LOOPBACK OMISSION. Nothing can
- * prove a client DID for an app on a local port — there is no domain serving a
- * well-known and no registration to check — so a host REFUSES a `client_did`
- * on a loopback redirect rather than displaying an identity it cannot stand
- * behind. A CLI that passed its own DID would have the whole request rejected,
- * not downgraded, so the param is dropped here instead of being forwarded into
- * a guaranteed refusal.
+ * The rule this function owns is the LOOPBACK RULE, and what it turns on is
+ * whether the request names a client identity. A bare `client_did` from an app
+ * on a local port used to be refused outright — there is no domain serving a
+ * well-known and no registration to check, so nothing backed the DID and a host
+ * would not display an identity it could not stand behind. The LOOPBACK
+ * CREDENTIAL TIER (specs/SIWD.md §Loopback Clients) replaces "nothing backs it"
+ * with the one thing local software can prove: control of that identity's
+ * current keys. So the param now rides through on a loopback redirect instead
+ * of being dropped — but it is honored only when the request ALSO carries an
+ * ask proof and, unless the DID is already resident on the host, the client's
+ * identity chain. `createSiwdLoopbackLoginRequest` composes all three; a
+ * `clientDid` passed to this function alone is an unbacked assertion the host
+ * will refuse.
  *
  * The same judgment BOUNDS THE SCOPE. Every scope past `identity` returns a
- * credential issued to a `client_did` — the one param a loopback request cannot
- * carry — so specs/SIWD.md admits a loopback target for `scope=identity` only.
- * Asking for more from a local port is not a downgrade the way `client_did` is;
- * there is nothing to drop, so it throws.
+ * credential issued to a `client_did`, so a loopback request with no client
+ * identity at all still has nothing to issue to and specs/SIWD.md admits it for
+ * `scope=identity` only — there is nothing to downgrade, so it throws. With a
+ * client identity the tier is open and every scope is available.
  *
  * It also owns the WIRE PARAM NAMES (`challenge`, `redirect_uri`, `scope`,
- * `client_did`) as their single source in this package. They are snake_case on
- * the wire and camelCase everywhere else, which is exactly the kind of seam
+ * `client_did`, and — via `createSiwdLoopbackLoginRequest` — `client_proof` and
+ * `client_chain`) as their single source in this package. They are snake_case
+ * on the wire and camelCase everywhere else, which is exactly the kind of seam
  * every hand-rolled RP re-implements and eventually gets wrong.
  *
  * PURE: no DOM, no storage, no navigation, no fetch — identical in a browser
  * and in Node. Throws on an unparseable `authorizeUrl` or `redirectUri`, and on
- * a non-`identity` scope over a loopback redirect, because those are mistakes
- * in the RP's own configuration rather than runtime conditions a result type
- * would help a caller recover from.
+ * a non-`identity` scope over a loopback redirect with no client identity,
+ * because those are mistakes in the RP's own configuration rather than runtime
+ * conditions a result type would help a caller recover from.
  */
 declare const createSiwdLoginRequest: (input: SiwdLoginRequestInput) => SiwdLoginRequest;
+/**
+ * Sign the ask proof for a loopback authorize request: a JWS over the exact
+ * canonical bytes of the request's own challenge, under `SIWD_ASK_JWS_TYP`,
+ * signed by a CURRENT auth key of the client identity's chain (SIWD.md §The ask
+ * proof). It is what makes a `client_did` on a loopback request mean something
+ * — the host verifies it against the chain's current state before rendering any
+ * consent, so key control is established at ask-time, not just at spend-time.
+ *
+ * BYTE-PRECISE, and deliberately not built with `createJws`. The host compares
+ * the proof's payload SEGMENT by string equality against its own re-derivation
+ * of `base64url(siwdSigningInput(challenge))`; a construction that round-tripped
+ * the challenge through a JSON object would re-serialize it, and any spelling
+ * that differed from the canonical one by a single byte would fail that
+ * comparison while looking correct here. So this signs the `siwdSigningInput`
+ * output directly.
+ *
+ * `kid` is the DID URL of the signing key. The host ignores it for key
+ * SELECTION — it tries the chain's current auth keys — but it is set honestly
+ * because a proof that names a key it was not signed with is a lie the wire
+ * format has no reason to carry.
+ *
+ * The `client_proof` param that carries this is the REFERENCE wire surface, not
+ * a normative name: SIWD.md defers how the ask proof travels to the hosted
+ * endpoint's reference implementation, exactly as it does the endpoint itself.
+ * What is normative is that it arrives WITH the ask and verifies BEFORE any
+ * consent is rendered.
+ */
+declare const signSiwdAskProof: (input: {
+    challenge: SiwdChallenge;
+    /** DID URL of the signing key: `<did>#<keyId>`. Must be a CURRENT auth key. */
+    kid: string;
+    signer: Signer;
+}) => Promise<string>;
+/** SIWD.md carriage cap — an identity that has outgrown it has outgrown carriage. */
+declare const MAX_SIWD_CLIENT_CHAIN_OPS = 100;
+/**
+ * Encode a client identity chain for carriage on the authorize request: the
+ * FULL ordered operation log, genesis first, as base64url of its JSON array —
+ * the same grammar as the `challenge` param, so one decoder shape serves both.
+ *
+ * THIS IS THE LOOPBACK CARRIAGE FORM, and only that. An application that holds a
+ * domain encodes nothing: it publishes the very same log as the raw JSON array
+ * of the `identity_chain` member of its `/.well-known/dfos-app.json` app
+ * description (SIWD.md §`identity_chain` — chain carriage), where the origin
+ * serving the file is what associates the domain with the DID. Same chain, same
+ * carriage rules — a URL is simply the carrier available to software that holds
+ * no origin to publish from.
+ *
+ * The DID derived from the genesis operation MUST equal the `client_did` the
+ * request names; a request where the two disagree makes no claim at all and the
+ * host refuses it WHOLE rather than ingesting the chain and ignoring the
+ * mismatch (SIWD.md §Chain residence). Carriage is only needed when the DID is
+ * not already resident on the verifying host.
+ *
+ * The 100-operation cap is spec-normative and enforced here. Hosts MAY
+ * additionally bound the ENCODED size for URL-transport reasons — the reference
+ * host refuses carriages over 8KiB — which is transport policy rather than
+ * protocol, so it is not a client-side throw; the practical reading is that a
+ * chain anywhere near the op cap belongs on relays, not in a URL.
+ *
+ * As with the ask proof, the `client_chain` param is the REFERENCE wire surface
+ * rather than a normative name — SIWD.md leaves the carriage encoding to the
+ * hosted endpoint's reference implementation and pins only that the chain
+ * arrives with the ask and verifies before any consent is rendered.
+ */
+declare const encodeSiwdClientChain: (log: string[]) => string;
+interface SiwdClientIdentity {
+    did: string;
+    /**
+     * Verbatim identity-op JWS log, genesis first. A loopback client feeds it to
+     * `encodeSiwdClientChain` to carry on the authorize URL; an application that
+     * holds a domain serves this same array verbatim as the `identity_chain`
+     * member of its app description document.
+     */
+    chain: string[];
+    /** DID URL of the current auth key — feed to signSiwdAskProof. */
+    kid: string;
+    signer: Signer;
+    /** Raw Ed25519 private key — persist it (with `chain`) to keep this DID across runs. */
+    privateKey: Uint8Array;
+}
+/**
+ * Mint a fresh client identity: one Ed25519 keypair and a single genesis
+ * `create` operation naming it as the auth, assertion, and controller key. That
+ * is an entire application identity — a DID whose key control is provable, and a
+ * one-operation chain small enough to travel anywhere a chain has to travel.
+ *
+ * TIER-AGNOSTIC. What comes back is an ordinary DFOS identity, not a
+ * loopback-only artifact; the tier is a property of how the identity is
+ * PRESENTED, not of the identity itself. An application that holds a domain
+ * serves `chain` verbatim as the `identity_chain` member of its
+ * `/.well-known/dfos-app.json` app description and names `did` as its
+ * `client_did` there; a loopback client carries the same chain on the authorize
+ * request instead (`createSiwdLoopbackLoginRequest`), because it has no origin
+ * to publish from. Both are minted here.
+ *
+ * KEY CUSTODY IS THE CALLER'S, and the identity is only as durable as the
+ * custody: persist `privateKey` and `chain` — an OS keychain, a file the caller
+ * protects — and hand them back to `restoreSiwdClientIdentity` on the next run.
+ * That is the other half of this function, and it is not optional in practice.
+ * A client that re-mints instead of restoring arrives as a DIFFERENT DID every
+ * time, so every run asks the user to consent again and every credential the
+ * last run earned belongs to an identity nothing will ever present again.
+ * Nothing here touches storage; where the key lives is the caller's to decide.
+ */
+declare const mintSiwdClientIdentity: () => Promise<SiwdClientIdentity>;
+/**
+ * Rebuild a client identity from what a previous run persisted — the other half
+ * of `mintSiwdClientIdentity`, and what makes the DID (and the consent it
+ * earned) survive across runs.
+ *
+ * It re-derives the public key from `privateKey` and finds the CURRENT auth key
+ * of the verified chain that key belongs to, which is the same currency rule the
+ * host applies to the ask proof. A key that has been ROTATED OUT of the chain
+ * therefore refuses to restore rather than producing an identity whose proofs
+ * would be rejected at the far end: failing here, with the reason in hand, is
+ * strictly better than failing after a redirect. The `kid` comes from the chain
+ * rather than from storage for the same reason — the chain is the authority on
+ * which key is current, and a persisted `kid` is a guess that ages.
+ *
+ * `chain` is the caller's stored log, and it is verified here, so a corrupted or
+ * truncated log surfaces as a throw rather than as a silently wrong DID.
+ */
+declare const restoreSiwdClientIdentity: (input: {
+    privateKey: Uint8Array;
+    /** The verbatim log `mintSiwdClientIdentity` returned, genesis first. */
+    chain: string[];
+}) => Promise<SiwdClientIdentity>;
+interface SiwdLoopbackLoginRequestInput {
+    /** The host's authorize endpoint, e.g. `https://app.example.com/authorize`. */
+    authorizeUrl: string;
+    /** Loopback redirect target — `http://` on localhost / 127.0.0.1 / [::1], any port/path. */
+    redirectUri: string;
+    /**
+     * Requested scope, in the same space-separated set form as
+     * `SiwdLoginRequestInput.scope`. Naming a client identity opens the tier, so
+     * every scope the HOST offers is available here — the `identity`-only bound
+     * belongs to the anonymous loopback shape, which has no `client_did` to issue
+     * a credential to.
+     */
+    scope: string;
+    /** Consent-screen prose. A host MAY decline to render it; see specs/SIWD.md. */
+    statement?: string;
+    /** Bind the challenge to ONE subject DID (sign in as this DID or not at all). */
+    did?: string;
+    /** The client identity asking under the loopback credential tier. */
+    client: Pick<SiwdClientIdentity, 'did' | 'kid' | 'signer'> & {
+        /** Verbatim chain to carry; omit when the DID is already resident on the host. */
+        chain?: string[];
+    };
+    /** Supply a nonce minted elsewhere; default: minted here. Verify against it. */
+    nonce?: string;
+}
+/**
+ * Build a loopback authorize URL under the LOOPBACK CREDENTIAL TIER — the
+ * outbound half of what `createSiwdLoginRequest` alone cannot produce. It is
+ * that function plus the two things that back the `client_did` it now carries:
+ * an ask proof (SIWD.md §The ask proof) and, unless the DID is already resident
+ * on the host, the client's identity chain (SIWD.md §Chain residence).
+ *
+ * `domain` is DERIVED, not accepted. SIWD.md pins a loopback challenge's domain
+ * to the BARE loopback host — the port is not part of the binding, because a
+ * local application cannot reserve one — and the host compares that value
+ * literally against the redirect's host. Taking a `domain` input here would be
+ * an invitation to a mismatch that fails only after the redirect.
+ *
+ * WHAT THIS PROVES IS KEY CONTROL, NOT PROVENANCE. The chain says which keys
+ * the asking party holds; nothing about a loopback client's origin or authorship
+ * is checkable, and the host's consent screen says exactly that rather than
+ * displaying a domain it cannot stand behind. The residue is bounded on the
+ * other side: a credential minted to a loopback client carries a hard expiry
+ * ceiling — RECOMMENDED 14 days — so a proven-but-unvouched-for client's grant
+ * ages out on its own, with revocation remaining the user's real disconnect.
+ *
+ * Async (it signs) and throwing on configuration errors — a `redirectUri` that
+ * is not an `http://` loopback target, a `kid` that does not belong to the
+ * client's own DID, a chain past the carriage cap — consistent with the
+ * constructor half of this module.
+ */
+declare const createSiwdLoopbackLoginRequest: (input: SiwdLoopbackLoginRequestInput) => Promise<SiwdLoginRequest>;
 /**
  * What came back on the redirect. `none` means this was a plain page load, not
  * a callback at all — the common case on an RP's own landing page.
@@ -166,6 +376,8 @@ type SiwdCallbackResult = {
     kind: 'success';
     jws: string;
     did: string;
+    /** Present only when the host minted one and the input carried a fragment. */
+    credential?: string;
 } | {
     kind: 'denied';
     error: string;
@@ -182,17 +394,39 @@ type SiwdCallbackResult = {
  * Takes an absolute URL string, a `URL`, or a bare `?…` query string (so
  * `readSiwdCallback(location.search)` works, including when it is empty).
  *
- * SCRUB THE URL YOURSELF, IMMEDIATELY. A signed JWS is sitting in the query
- * string, which means it is in the address bar, in `history`, in the referrer
- * of anything the page loads next, and in any analytics that samples the
- * location. This function cannot do the scrubbing for you — `history` is
- * environment-owned and this package stays free of the DOM — so a browser RP
- * should follow the read with a `history.replaceState` back to the bare path.
+ * A CREDENTIAL COMES BACK IN THE FRAGMENT, and that is a deliberate asymmetry
+ * with `jws`/`did`, which ride the query. A fragment is never sent to a server:
+ * it lands in no access log, no proxy log, and no `Referer` header, so the one
+ * artifact that is redeemable outside this channel is the one that stays on the
+ * client. Reading it therefore requires the WHOLE URL — `location.href`, not
+ * `location.search`.
+ *
+ * THAT SAME PROPERTY IS A PROBLEM FOR A CLI, and this tier's primary consumer is
+ * a CLI. A browser does not send the fragment to the loopback listener either,
+ * so the request line a local HTTP server sees carries the query and nothing
+ * else. The standard resolution (SIWD.md §4's loopback note) is for the listener
+ * to answer with a small page whose script reads `location.href` and posts the
+ * whole URL back to the local server; feed THAT to this function. A browser RP
+ * passes `location.href` directly and needs no relay.
+ *
+ * SCRUB THE URL YOURSELF, IMMEDIATELY. The signed JWS in the query string is in
+ * the address bar, in `history`, in the referrer of anything the page loads
+ * next, and in any analytics that samples the location; a credential in the
+ * fragment is spared the referrer and the server-side logs but is in the address
+ * bar and `history` just the same. This function cannot do the scrubbing for you
+ * — `history` is environment-owned and this package stays free of the DOM — so a
+ * browser RP should follow the read with a `history.replaceState` back to the
+ * bare path, which clears both halves.
  *
  * A HALF-CALLBACK IS A FAILURE, NOT A NON-EVENT: `jws` without `did` (or the
  * reverse) resolves to `denied` carrying a synthetic reason rather than `none`.
  * Silently treating it as a plain page load would strand the user on a
  * sign-in button with no explanation of why the last attempt vanished.
+ *
+ * THE QUERY HALF'S VERDICT WINS. A credential in the fragment is lifted only
+ * onto a `success`, never on its own: a `denied` or `none` stays exactly what
+ * it was. There is no half-callback state a stray fragment could promote —
+ * a fragment on a non-callback page load is noise, not a session.
  */
 declare const readSiwdCallback: (url: string | URL) => SiwdCallbackResult;
 interface BuildSiwdSignRequestInput {
@@ -273,4 +507,4 @@ interface SiwdExpectations {
  */
 declare const verifySiwd: (client: Client, jws: string, expect: SiwdExpectations) => Promise<VerifyResult<SiwdSession>>;
 
-export { type BuildSiwdSignRequestInput, type CreateChallengeInput, SIWD_JWS_TYP, type SiwdCallbackResult, type SiwdChallenge, type SiwdExpectations, type SiwdLoginRequest, type SiwdLoginRequestInput, type SiwdSession, type ValidateSiwdSignRequestOptions, type ValidatedSiwdSignRequest, buildSiwdSignRequest, createSiwdChallenge, createSiwdLoginRequest, decodeSiwdChallenge, parseSiwdChallenge, readSiwdCallback, siwdSigningInput, validateSiwdSignRequest, verifySiwd };
+export { type BuildSiwdSignRequestInput, type CreateChallengeInput, MAX_SIWD_CLIENT_CHAIN_OPS, SIWD_ASK_JWS_TYP, SIWD_JWS_TYP, type SiwdCallbackResult, type SiwdChallenge, type SiwdClientIdentity, type SiwdExpectations, type SiwdLoginRequest, type SiwdLoginRequestInput, type SiwdLoopbackLoginRequestInput, type SiwdSession, type ValidateSiwdSignRequestOptions, type ValidatedSiwdSignRequest, buildSiwdSignRequest, createSiwdChallenge, createSiwdLoginRequest, createSiwdLoopbackLoginRequest, decodeSiwdChallenge, encodeSiwdClientChain, mintSiwdClientIdentity, parseSiwdChallenge, readSiwdCallback, restoreSiwdClientIdentity, signSiwdAskProof, siwdSigningInput, validateSiwdSignRequest, verifySiwd };

package/dist/siwd.js

@@ -2,18 +2,26 @@
 import {
   buildSignRequest,
   decodeMultikey,
+  encodeEd25519Multikey,
+  signIdentityOperation,
   SignRequestVerifyError,
+  verifyIdentityChain,
   verifySignRequest
 } from "@metalabel/dfos-protocol/chain";
 import {
   assertJwsProfile,
   base64urlDecode,
   base64urlEncode,
+  createNewEd25519Keypair,
   decodeJwsUnsafe,
+  generateId,
   generateIdNoPrefix,
+  importEd25519Keypair,
+  signPayloadEd25519,
   verifyJws
 } from "@metalabel/dfos-protocol/crypto";
 var SIWD_JWS_TYP = "did:dfos:siwd";
+var SIWD_ASK_JWS_TYP = "did:dfos:siwd-ask";
 var MAX_CLOCK_SKEW_SECONDS = 60;
 var SIWD_CHALLENGE_FIELDS = /* @__PURE__ */ new Set(["domain", "nonce", "timestamp", "statement", "did"]);
 var WHOLE_SECOND_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.000Z$/;
@@ -125,8 +133,10 @@ var createSiwdLoginRequest = (input) => {
   const authorizeUrl = parseUrlOrThrow(input.authorizeUrl, "authorizeUrl");
   const redirect = parseUrlOrThrow(input.redirectUri, "redirectUri");
   const isLoopback = SIWD_LOOPBACK_HOSTS.has(bareHostname(redirect));
-  if (isLoopback && input.scope !== "identity") {
-    throw new Error("invalid SIWD login request: loopback redirects support scope=identity only");
+  if (isLoopback && input.scope !== "identity" && input.clientDid === void 0) {
+    throw new Error(
+      "invalid SIWD login request: loopback redirects support scope=identity only without a client identity \u2014 a credential scope needs a client_did proven under the loopback credential tier (specs/SIWD.md \xA7Loopback Clients)"
+    );
   }
   const { challenge, encoded, nonce } = createSiwdChallenge({
     domain: input.domain,
@@ -138,7 +148,7 @@ var createSiwdLoginRequest = (input) => {
   url.searchParams.set("challenge", encoded);
   url.searchParams.set("redirect_uri", input.redirectUri);
   url.searchParams.set("scope", input.scope);
-  if (input.clientDid !== void 0 && !isLoopback) {
+  if (input.clientDid !== void 0) {
     url.searchParams.set("client_did", input.clientDid);
   }
   return {
@@ -152,21 +162,152 @@ var createSiwdLoginRequest = (input) => {
     timestamp: challenge.timestamp
   };
 };
+var signSiwdAskProof = async (input) => {
+  const hashIdx = input.kid.indexOf("#");
+  if (hashIdx <= 0 || hashIdx === input.kid.length - 1) {
+    throw new Error(
+      "invalid SIWD ask proof: kid must be a DID URL with both halves non-empty (<did>#<keyId>)"
+    );
+  }
+  const headerB64 = base64urlEncode(
+    JSON.stringify({ alg: "EdDSA", typ: SIWD_ASK_JWS_TYP, kid: input.kid })
+  );
+  const payloadB64 = base64urlEncode(siwdSigningInput(input.challenge));
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const signature = await input.signer(new TextEncoder().encode(signingInput));
+  return `${signingInput}.${base64urlEncode(signature)}`;
+};
+var MAX_SIWD_CLIENT_CHAIN_OPS = 100;
+var encodeSiwdClientChain = (log) => {
+  if (!Array.isArray(log)) {
+    throw new Error("invalid SIWD client chain: expected an array of identity-op JWS strings");
+  }
+  if (log.length === 0) {
+    throw new Error("invalid SIWD client chain: log is empty \u2014 carriage needs the full log");
+  }
+  if (log.length > MAX_SIWD_CLIENT_CHAIN_OPS) {
+    throw new Error(
+      `invalid SIWD client chain: ${log.length} operations exceeds the ${MAX_SIWD_CLIENT_CHAIN_OPS}-operation carriage cap`
+    );
+  }
+  if (log.some((operation) => typeof operation !== "string" || operation.length === 0)) {
+    throw new Error(
+      "invalid SIWD client chain: every member must be a non-empty identity-op JWS string"
+    );
+  }
+  return base64urlEncode(JSON.stringify(log));
+};
+var mintSiwdClientIdentity = async () => {
+  const keypair = createNewEd25519Keypair();
+  const keyId = generateId("key");
+  const key = {
+    id: keyId,
+    type: "Multikey",
+    publicKeyMultibase: encodeEd25519Multikey(keypair.publicKey)
+  };
+  const signer = async (message) => signPayloadEd25519(message, keypair.privateKey);
+  const genesis = {
+    version: 1,
+    type: "create",
+    authKeys: [key],
+    assertKeys: [key],
+    controllerKeys: [key],
+    createdAt: new Date(Math.floor(Date.now() / 1e3) * 1e3).toISOString()
+  };
+  const { jwsToken } = await signIdentityOperation({ operation: genesis, signer, keyId });
+  const { did } = await verifyIdentityChain({ didPrefix: "did:dfos", log: [jwsToken] });
+  return {
+    did,
+    chain: [jwsToken],
+    kid: `${did}#${keyId}`,
+    signer,
+    privateKey: keypair.privateKey
+  };
+};
+var restoreSiwdClientIdentity = async (input) => {
+  const keypair = importEd25519Keypair(input.privateKey);
+  const identity = await verifyIdentityChain({ didPrefix: "did:dfos", log: input.chain });
+  const authKey = identity.authKeys.find((key) => {
+    const keyBytes = decodeMultikey(key.publicKeyMultibase).keyBytes;
+    return keyBytes.length === keypair.publicKey.length && keyBytes.every((byte, index) => byte === keypair.publicKey[index]);
+  });
+  if (!authKey) {
+    throw new Error(
+      "invalid SIWD client identity: the private key is not a CURRENT authentication key of the supplied chain \u2014 a rotated-out key cannot restore, because the host would refuse the ask proof it signs"
+    );
+  }
+  return {
+    did: identity.did,
+    chain: input.chain,
+    kid: `${identity.did}#${authKey.id}`,
+    signer: async (message) => signPayloadEd25519(message, keypair.privateKey),
+    privateKey: input.privateKey
+  };
+};
+var createSiwdLoopbackLoginRequest = async (input) => {
+  const redirect = parseUrlOrThrow(input.redirectUri, "redirectUri");
+  const domain = bareHostname(redirect);
+  if (!SIWD_LOOPBACK_HOSTS.has(domain) || redirect.protocol !== "http:") {
+    throw new Error(
+      "invalid SIWD login request: redirectUri must be an http:// loopback target (localhost, 127.0.0.1, [::1])"
+    );
+  }
+  if (!input.client.kid.startsWith(`${input.client.did}#`)) {
+    throw new Error(
+      "invalid SIWD login request: client.kid must be a DID URL of client.did (<did>#<keyId>)"
+    );
+  }
+  const request = createSiwdLoginRequest({
+    authorizeUrl: input.authorizeUrl,
+    domain,
+    redirectUri: input.redirectUri,
+    scope: input.scope,
+    clientDid: input.client.did,
+    ...input.statement !== void 0 ? { statement: input.statement } : {},
+    ...input.did !== void 0 ? { did: input.did } : {},
+    ...input.nonce !== void 0 ? { nonce: input.nonce } : {}
+  });
+  const proof = await signSiwdAskProof({
+    challenge: decodeSiwdChallenge(request.challenge),
+    kid: input.client.kid,
+    signer: input.client.signer
+  });
+  const url = new URL(request.url);
+  url.searchParams.set("client_proof", proof);
+  if (input.client.chain !== void 0) {
+    url.searchParams.set("client_chain", encodeSiwdClientChain(input.client.chain));
+  }
+  return { ...request, url: url.toString() };
+};
 var callbackParam = (params, key) => {
   const value = params.get(key);
   return value === null || value === "" ? void 0 : value;
 };
-var callbackParams = (url) => {
-  if (typeof url !== "string") return url.searchParams;
-  if (url === "" || url.startsWith("?")) return new URLSearchParams(url);
-  return parseUrlOrThrow(url, "url").searchParams;
+var callbackParts = (url) => {
+  if (typeof url === "string" && (url === "" || url.startsWith("?"))) {
+    const hashIdx = url.indexOf("#");
+    const hash2 = hashIdx < 0 ? "" : url.slice(hashIdx + 1);
+    return {
+      query: new URLSearchParams(hashIdx < 0 ? url : url.slice(0, hashIdx)),
+      ...hash2 !== "" ? { fragment: new URLSearchParams(hash2) } : {}
+    };
+  }
+  const parsed = typeof url === "string" ? parseUrlOrThrow(url, "url") : url;
+  const hash = parsed.hash.startsWith("#") ? parsed.hash.slice(1) : parsed.hash;
+  return {
+    query: parsed.searchParams,
+    ...hash !== "" ? { fragment: new URLSearchParams(hash) } : {}
+  };
 };
 var readSiwdCallback = (url) => {
-  const params = callbackParams(url);
-  const jws = callbackParam(params, "jws");
-  const did = callbackParam(params, "did");
-  const error = callbackParam(params, "error");
-  if (jws !== void 0 && did !== void 0) return { kind: "success", jws, did };
+  const { query, fragment } = callbackParts(url);
+  const jws = callbackParam(query, "jws");
+  const did = callbackParam(query, "did");
+  const error = callbackParam(query, "error");
+  if (jws !== void 0 && did !== void 0) {
+    const credential = fragment ? callbackParam(fragment, "credential") : void 0;
+    return { kind: "success", jws, did, ...credential !== void 0 ? { credential } : {} };
+  }
   if (error !== void 0) return { kind: "denied", error };
   if (jws !== void 0) return { kind: "denied", error: "malformed SIWD callback: missing did" };
   if (did !== void 0) return { kind: "denied", error: "malformed SIWD callback: missing jws" };
@@ -321,13 +462,20 @@ var verifySiwd = async (client, jws, expect) => {
   }
 };
 export {
+  MAX_SIWD_CLIENT_CHAIN_OPS,
+  SIWD_ASK_JWS_TYP,
   SIWD_JWS_TYP,
   buildSiwdSignRequest,
   createSiwdChallenge,
   createSiwdLoginRequest,
+  createSiwdLoopbackLoginRequest,
   decodeSiwdChallenge,
+  encodeSiwdClientChain,
+  mintSiwdClientIdentity,
   parseSiwdChallenge,
   readSiwdCallback,
+  restoreSiwdClientIdentity,
+  signSiwdAskProof,
   siwdSigningInput,
   validateSiwdSignRequest,
   verifySiwd

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-client",
-  "version": "0.35.0",
+  "version": "0.36.1",
   "type": "module",
   "description": "DFOS Client — the client-side kit for participating in the protocol: resolve, verify, prove. Fetch, resolve, verify-orchestration and cache over untrusted relays, plus the SIWD and API-AUTH proof surfaces. Holds no keys; all crypto truth comes from @metalabel/dfos-protocol",
   "license": "MIT",
@@ -47,15 +47,15 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@metalabel/dfos-protocol": "^0.35.0",
-    "@metalabel/dfos-web-relay": "^0.35.0"
+    "@metalabel/dfos-protocol": "^0.36.1",
+    "@metalabel/dfos-web-relay": "^0.36.1"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "vitest": "^4.1.8",
-    "@metalabel/dfos-protocol": "0.35.0",
-    "@metalabel/dfos-web-relay": "0.35.0"
+    "@metalabel/dfos-protocol": "0.36.1",
+    "@metalabel/dfos-web-relay": "0.36.1"
   },
   "scripts": {
     "build": "tsup",