@estiva-app/identity 0.1.3 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @estiva-app/identity
 
+## 0.2.1 — 2026-09-08
+
+**Additive.** `SignRefused` is new; nothing that catches `Error` or reads a
+message changes.
+
+- **A `/sign` refusal that is not an expiry now throws `SignRefused`, carrying
+  the HTTP `status`.** A `401` still throws `SignerTokenExpired`, which is the
+  one refusal a new token fixes.
+
+  The status belongs on the error because **consumers classify on it and a
+  message is not an API.** Found while wiring Peek as the third consumer:
+  `reasonForSignFailure` maps `/sign` failures into the auth shell's reason
+  vocabulary by regexing `POST /sign failed: (\d{3})` out of the message Peek's
+  own copy threw. `403` is `identity_inactive` — an administrator has to restore
+  the identity — while a `422` policy refusal is not, and neither is a `502`.
+
+  Swapping in this package's differently worded message would have collapsed
+  every one of those into a single reason. **Nothing would have failed**: Peek's
+  tests pass literal strings rather than real errors, so the regex kept matching
+  in the test suite while matching nothing in production. That is the shape worth
+  recording — the test and the code agreed with each other and both stopped
+  describing the app.
+
+## 0.2.0 — 2026-09-07
+
+**MINOR because it adds a peer dependency**, which is a break for a consumer
+that does not already have `@estiva-app/protocol` — ADR 0002 §4b puts the break
+on MINOR within `0.x`. Both consumers already have it, and per §5 both had an
+open upgrade PR before this published.
+
+**`POST /sign` lives here now.** SHA-3 left `estivaIdSigner` behind in the apps
+deliberately — "it knows about Estiva ID, which is this ticket" — and SHA-4's
+handoff comment called it "the one thing left duplicated between ship and
+estiva-agent, byte-identical, and it is yours to remove". This is that.
+
+- **New: `signViaEstivaId(unsigned, { base, token, expectedPubkey })`** — one
+  round trip. What Peek uses, because Peek signs per request with a token it
+  reads fresh each time.
+
+- **New: `estivaIdSigner({ base, pubkey, token, renew })`** — a `Signer` over the
+  same round trip, holding a live bearer and renewing once on a `401`. What Ship
+  uses, because Ship builds one signer at module scope for the life of the page.
+  Neither shape can be expressed as the other without one of them getting worse,
+  so both are here over one implementation.
+
+- **`SignerTokenExpired`** travels with them: "obtain a new token" and "this
+  event was refused" call for different things from the caller, and the status
+  code is the only thing that separates them.
+
+### The guard the three copies had already drifted on
+
+`/sign` **signs as the token's subject regardless of what it is handed.** So a
+token that belongs to somebody else does not produce an error — it produces
+**HTTP 200 carrying a valid event authored by that other person**, and the
+symptom arrives much later as a comment attributed to a colleague, with nothing
+in any log tying it back.
+
+SHA-4's Traps section says both apps must keep the `expectedPubkey` guard. **Only
+Peek's did.** Ship's `estivaIdSigner` — the signer every issue, comment, status
+change and assignment in Ship goes through — never had a pubkey comparison at
+all. That is precisely the drift three copies of one call produce, and the app
+that could least afford it was the one missing it.
+
+Here the guard is not optional on the `estivaIdSigner` path: it is supplied from
+the `pubkey` the signer was built with, whether or not the caller thought about
+it. Two tests cover it and a control asserts a wrong-author refusal does **not**
+trigger a renewal — spending a single-use refresh token on an error a new token
+cannot fix is how one bad signature becomes a revoked chain.
+
+### What stayed in the apps, and why
+
+`localSigner` (a per-browser anonymous key) and `nip07Signer` (a browser
+extension) are still duplicated between `ship` and `estiva-agent`, held by
+`scripts/conformance.test.ts`. Neither knows anything about Estiva ID, which is
+the line this package draws, so neither moved. Worth its own ticket rather than
+a quiet widening of this one.
+
+### The seam property still holds
+
+`@estiva-app/protocol` is a **peer** dependency, following `@estiva-app/interop`.
+Nothing here calls a protocol function — only its types are used — so the
+complete list of imports in the shipped JavaScript is still `./client.js`,
+`./shell.js` and now `./signer.js`. Only the `.d.ts` names protocol.
+
 ## 0.1.3 — 2026-09-07
 
 **Fixes a dead end reported from production.** No API change; `expiresAt` is now
@@ -39,6 +123,7 @@ still held: a token this cannot read is still a token.
 5 new tests, 59 to 64, including two controls that the `expires_in` fallback is
 untouched. Reverting the clamp fails exactly the two tests that depend on it.
 
+
 ## 0.1.2 — 2026-09-07
 
 **No wire behaviour, no break.** `scheduleRenewal` is new and the guard on

package/README.md

@@ -69,6 +69,36 @@ const client = createEstivaId({
 export const { validToken, beginSignIn, completeSignIn, beginSignOut } = client
 ```
 
+## Signing is asking, and the answer must be checked
+
+```ts
+// Peek: one round trip, a token read fresh each time
+const event = await signViaEstivaId(unsigned, { base, token, expectedPubkey: myPubkey })
+
+// Ship: a protocol Signer, built once, renewing itself
+const signer = estivaIdSigner({ base, pubkey, token, renew: client.refreshAccessToken })
+```
+
+An app publishes as a person without ever seeing their secret. `@estiva-app/protocol`
+owns how an event gets its signature; this package owns *who is allowed to ask*.
+
+**`/sign` signs as the token's subject regardless of what it is handed.** So a
+token belonging to somebody else is not an error — it is **HTTP 200 with a valid
+event authored by that other person**. `expectedPubkey` is a check, not a
+request, and `estivaIdSigner` supplies it unconditionally from the pubkey it was
+built with. There were three copies of this round trip before SHA-4 and only one
+of them checked; the one that did not was Ship's, through which every write in
+Ship passes.
+
+A `401` throws `SignerTokenExpired`; any other refusal throws `SignRefused`
+carrying the HTTP `status`, because consumers classify on it and a message is not
+an API — `403` means an administrator has to restore the identity, while a `422`
+policy refusal means something else entirely. And
+`estivaIdSigner` renews **once** and retries. Never twice: a second `401` after
+a successful renewal is a token the service will not accept, and retrying that
+is how one refused signature becomes a hot loop. Anything that is not an expiry
+is rethrown untouched, so a wrong-author refusal never spends a refresh token.
+
 ## Renewal is scheduled, not reactive
 
 ```ts

package/dist/index.d.ts

@@ -46,7 +46,8 @@
  * The thing that made it possible was not cleverness — it was that a browser API
  * an app must inject is also a browser API a test can observe.
  */
-export declare const IDENTITY_VERSION = "0.1.3";
+export declare const IDENTITY_VERSION = "0.2.1";
 export { type KeyValueStore, type ShellPhase, type ShellReason, type ShellState, type BootObservation, type BootAction, type ShellEvent, isRecoverable, SHELL_COPY, CONTINUE_LABEL, RETRY_LABEL, PROBE_TIMEOUT_MS, GUARD_TTL_MS, GUARD_KEY, decideBoot, reasonForCallbackError, readGuard, markGuard, clearGuard, logShellEvent, } from './shell.js';
 export { type EstivaIdConfig, type EstivaIdClient, type StoredToken, type FetchLike, type RenewalHandlers, type RenewalSchedule, SignInError, createEstivaId, } from './client.js';
+export { type SignViaEstivaIdOptions, type EstivaIdSignerOptions, type SignFetchLike, SignerTokenExpired, SignRefused, signViaEstivaId, estivaIdSigner, } from './signer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,cAAc,GACf,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -46,7 +46,8 @@
  * The thing that made it possible was not cleverness — it was that a browser API
  * an app must inject is also a browser API a test can observe.
  */
-export const IDENTITY_VERSION = '0.1.3';
+export const IDENTITY_VERSION = '0.2.1';
 export { isRecoverable, SHELL_COPY, CONTINUE_LABEL, RETRY_LABEL, PROBE_TIMEOUT_MS, GUARD_TTL_MS, GUARD_KEY, decideBoot, reasonForCallbackError, readGuard, markGuard, clearGuard, logShellEvent, } from './shell.js';
 export { SignInError, createEstivaId, } from './client.js';
+export { SignerTokenExpired, SignRefused, signViaEstivaId, estivaIdSigner, } from './signer.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEvC,OAAO,EAQL,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAA;AAEnB,OAAO,EAOL,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEvC,OAAO,EAQL,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAA;AAEnB,OAAO,EAOL,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAA;AAEpB,OAAO,EAIL,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,cAAc,GACf,MAAM,aAAa,CAAA"}

package/dist/signer.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Signing by asking Estiva ID, holding no key at all.
+ *
+ * The point of the whole seam: an app publishes as a person without ever seeing
+ * their secret. `POST /sign` takes a bearer token and an unsigned event and
+ * returns a signed one.
+ *
+ * ## Why this is identity's and not protocol's
+ *
+ * `@estiva-app/protocol` owns how an event gets its signature — the id
+ * computation, the serialization, the bytes. It owns the {@link Signer} seam and
+ * the raw-secret-key implementation of it. What it deliberately does not own is
+ * *who is allowed to ask*: the token, its renewal, and the round trip to an
+ * identity service. That is this package, and `ship/lib/nostr/signer.ts` has
+ * said so in a header comment since SHA-3 — "it is `@estiva-app/identity`'s
+ * remit — SHA-4. Until then this file is the app's copy."
+ *
+ * There were three copies until this file existed:
+ *
+ * | where | what |
+ * | --- | --- |
+ * | `ship/lib/nostr/signer.ts` | `estivaIdSigner` |
+ * | `estiva-agent/lib/nostr/signer.ts` | byte-identical to it |
+ * | `peek/src/nostr/bridge.ts` | `signViaEstivaId`, a third |
+ *
+ * Three implementations of the one call that decides who authored an event, and
+ * they had already drifted on the thing that matters most — see the guard below.
+ *
+ * ## Two exports over one round trip
+ *
+ * The consumers genuinely want different shapes, and this is not the same kind
+ * of difference as `storage` or `clientId`. Peek signs *per request* with a token
+ * it reads fresh each time (`signViaEstivaId`); Ship builds a `Signer` **once**,
+ * at module scope, which then holds a live bearer for the life of the page and
+ * renews it on a `401`. Neither can be expressed as the other without one of
+ * them getting worse, so both are here, over one implementation of the round
+ * trip and one copy of the guard.
+ *
+ * `@estiva-app/protocol` is a **peer** dependency, following `@estiva-app/interop`.
+ * Nothing here calls a protocol function — only its types are used — so the
+ * emitted `.js` imports nothing, and `dist/` keeps the property SHA-4's seam was
+ * verified by: the complete list of imports in the shipped JavaScript is
+ * `./client.js` and `./shell.js`.
+ */
+import type { SignedEvent, Signer, UnsignedEvent } from '@estiva-app/protocol';
+/**
+ * `fetch`, again, and for the same reason as in `client.ts` — `lib.es2022` has
+ * no such global, and this package compiles with `types: []` and no `lib: dom`
+ * so one published `.d.ts` works in every consumer (ADR 0002 §4a).
+ *
+ * Note this module needs a *slightly* wider `fetch` than `client.ts` does: it
+ * reads `text()` rather than `json()`, because `/sign`'s error bodies are not
+ * reliably JSON and the raw text is the only thing worth showing a person.
+ */
+declare const fetch: (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** Just the part of `fetch` this module uses. A parameter as well as a global. */
+export type SignFetchLike = typeof fetch;
+/** Distinguishes "sign in again" from "this event was refused". */
+export declare class SignerTokenExpired extends Error {
+    constructor();
+}
+/**
+ * A refusal that is not an expiry, **carrying the status that says which**.
+ *
+ * The status is on the error rather than only in its text because consumers
+ * classify on it and a message is not an API. Peek maps `/sign` failures into
+ * the auth shell's reason vocabulary — `403` is `identity_inactive`, an
+ * administrator's problem, while a `422` policy refusal is not — and it did that
+ * by regexing its own thrown string. A package that threw a differently worded
+ * message would have quietly collapsed every one of those into the same reason,
+ * and Peek's tests pass literal strings, so nothing would have failed.
+ */
+export declare class SignRefused extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export interface SignViaEstivaIdOptions {
+    /** Origin of the identity service, e.g. `https://id.estiva.app`. */
+    base: string;
+    /** A bearer token from `POST /token`, audience-bound to this app. */
+    token: string;
+    /**
+     * The pubkey the returned event **must** be authored by.
+     *
+     * Not a request. `/sign` ignores any pubkey it is handed and signs as the
+     * token's subject, always — so this is a *check*, and the reason one is needed
+     * at all is that a mismatch comes back as **HTTP 200 with a perfectly valid
+     * event authored by somebody else**. Without it the failure is invisible at
+     * the call site and surfaces later as a message attributed to the wrong
+     * person, which is not a bug anybody can debug from the symptom.
+     *
+     * Optional only because `estivaIdSigner` always supplies it and a caller with
+     * genuinely no expectation should be able to say so out loud. Supply it.
+     */
+    expectedPubkey?: string;
+    fetch?: SignFetchLike;
+}
+/**
+ * One `POST /sign`.
+ *
+ * **`/sign` refuses `kind:0` for every app, always.** Profiles belong to the
+ * identity service (PEEK-31); a refusal here is the policy working rather than
+ * something to route around.
+ *
+ * A `401` is thrown as {@link SignerTokenExpired} rather than a generic failure,
+ * because "obtain a new token" and "this event was refused" call for completely
+ * different responses from the caller and the status code is the only thing that
+ * distinguishes them.
+ */
+export declare function signViaEstivaId(unsigned: UnsignedEvent, options: SignViaEstivaIdOptions): Promise<SignedEvent>;
+export interface EstivaIdSignerOptions {
+    /** Origin of the identity service, e.g. `https://id.estiva.app`. */
+    base: string;
+    /** The pubkey the token was issued for — `sub` in the JWT. */
+    pubkey: string;
+    /** A bearer token from `POST /token`, audience-bound to this app. */
+    token: string;
+    /**
+     * Renew the token, once, when `/sign` says it has expired (PEEK-108).
+     *
+     * Optional: without it a `401` surfaces as {@link SignerTokenExpired} for the
+     * caller to deal with, exactly as before. With it, an expiry is invisible —
+     * which matters more than it used to, because access tokens live ten minutes
+     * rather than an hour, so a session of any length crosses one.
+     *
+     * Returning `null` means renewal failed and the expiry is real.
+     *
+     * Pass `client.refreshAccessToken` and nothing else: it coalesces concurrent
+     * callers, and a refresh token is single-use with a replay read as theft.
+     */
+    renew?: () => Promise<string | null>;
+    fetch?: SignFetchLike;
+}
+/**
+ * A {@link Signer} that signs by asking Estiva ID.
+ *
+ * Holds the live bearer, so a renewal replaces it for every later signature
+ * rather than being rediscovered on each one.
+ */
+export declare function estivaIdSigner({ base, pubkey, token, renew, fetch: send }: EstivaIdSignerOptions): Signer;
+export {};
+//# sourceMappingURL=signer.d.ts.map

package/dist/signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../src/signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAE9E;;;;;;;;GAQG;AACH,OAAO,CAAC,MAAM,KAAK,EAAE,CACnB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KACpE,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAAA;AAEtE,kFAAkF;AAClF,MAAM,MAAM,aAAa,GAAG,OAAO,KAAK,CAAA;AAExC,mEAAmE;AACnE,qBAAa,kBAAmB,SAAQ,KAAK;;CAK5C;AAED;;;;;;;;;;GAUG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,WAAW,CAAC,CAkDtB;AAED,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACpC,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,qBAAqB,GAAG,MAAM,CAwCzG"}

package/dist/signer.js

@@ -0,0 +1,133 @@
+/** Distinguishes "sign in again" from "this event was refused". */
+export class SignerTokenExpired extends Error {
+    constructor() {
+        super('The signing token has expired');
+        this.name = 'SignerTokenExpired';
+    }
+}
+/**
+ * A refusal that is not an expiry, **carrying the status that says which**.
+ *
+ * The status is on the error rather than only in its text because consumers
+ * classify on it and a message is not an API. Peek maps `/sign` failures into
+ * the auth shell's reason vocabulary — `403` is `identity_inactive`, an
+ * administrator's problem, while a `422` policy refusal is not — and it did that
+ * by regexing its own thrown string. A package that threw a differently worded
+ * message would have quietly collapsed every one of those into the same reason,
+ * and Peek's tests pass literal strings, so nothing would have failed.
+ */
+export class SignRefused extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'SignRefused';
+    }
+}
+/**
+ * One `POST /sign`.
+ *
+ * **`/sign` refuses `kind:0` for every app, always.** Profiles belong to the
+ * identity service (PEEK-31); a refusal here is the policy working rather than
+ * something to route around.
+ *
+ * A `401` is thrown as {@link SignerTokenExpired} rather than a generic failure,
+ * because "obtain a new token" and "this event was refused" call for completely
+ * different responses from the caller and the status code is the only thing that
+ * distinguishes them.
+ */
+export async function signViaEstivaId(unsigned, options) {
+    const send = options.fetch ?? fetch;
+    const origin = options.base.replace(/\/+$/, '');
+    const response = await send(`${origin}/sign`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            authorization: `Bearer ${options.token}`,
+        },
+        /*
+          Only the four fields that go into the signature input. The unsigned event
+          may carry a `pubkey` — Peek's NIP-98 path passes an empty one on purpose —
+          and sending it would imply `/sign` honours it, which it does not.
+        */
+        body: JSON.stringify({
+            event: {
+                kind: unsigned.kind,
+                created_at: unsigned.created_at,
+                tags: unsigned.tags,
+                content: unsigned.content,
+            },
+        }),
+    });
+    const text = await response.text();
+    if (response.status === 401)
+        throw new SignerTokenExpired();
+    if (!response.ok) {
+        let reason = text.slice(0, 200);
+        try {
+            const body = JSON.parse(text);
+            reason = body.error?.message ?? reason;
+        }
+        catch {
+            // Keep the raw text. `/sign`'s error bodies are not reliably JSON, and the
+            // raw text is more use to a person than "unparseable response".
+        }
+        throw new SignRefused(response.status, `Estiva ID refused to sign kind:${unsigned.kind} — ${reason}`);
+    }
+    const event = JSON.parse(text).event;
+    if (!event)
+        throw new Error('POST /sign returned no event');
+    if (options.expectedPubkey && event.pubkey !== options.expectedPubkey) {
+        throw new Error(`POST /sign returned an event authored by ${event.pubkey}, expected ${options.expectedPubkey}. ` +
+            'That token belongs to a different identity — refusing to publish under the wrong author.');
+    }
+    return event;
+}
+/**
+ * A {@link Signer} that signs by asking Estiva ID.
+ *
+ * Holds the live bearer, so a renewal replaces it for every later signature
+ * rather than being rediscovered on each one.
+ */
+export function estivaIdSigner({ base, pubkey, token, renew, fetch: send }) {
+    let bearer = token;
+    return {
+        pubkey,
+        kind: 'estiva-id',
+        async sign(unsigned) {
+            const once = (auth) => signViaEstivaId(unsigned, {
+                base,
+                token: auth,
+                // The guard, unconditionally. Ship's copy of this signer never had it
+                // and Peek's `signViaEstivaId` did, which is exactly the drift three
+                // copies produce: the app that publishes every issue, comment and
+                // status change was the one that could not tell it had signed as
+                // somebody else. SHA-4's Traps section says both must keep it.
+                expectedPubkey: pubkey,
+                ...(send ? { fetch: send } : {}),
+            });
+            try {
+                return await once(bearer);
+            }
+            catch (error) {
+                /*
+                  Renew once and retry, never twice.
+        
+                  A second 401 after a successful renewal is not an expiry — it is a
+                  token the service will not accept, and retrying that in a loop is how
+                  one refused signature becomes a hot loop against the identity service.
+                  Anything that is not an expiry is rethrown untouched, so a wrong-author
+                  refusal is never mistaken for something a new token would fix.
+                */
+                if (!(error instanceof SignerTokenExpired) || !renew)
+                    throw error;
+                const renewed = await renew();
+                if (!renewed)
+                    throw error;
+                bearer = renewed;
+                return await once(bearer);
+            }
+        },
+    };
+}
+//# sourceMappingURL=signer.js.map

package/dist/signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../src/signer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@estiva-app/identity",
-  "version": "0.1.3",
-  "description": "Estiva ID sign-in: authorization code + PKCE, token storage, silent renewal, sign-out, and the auth-shell state machine. Knows nothing about any app's data layer.",
+  "version": "0.2.1",
+  "description": "Estiva ID sign-in: authorization code + PKCE, token storage, silent renewal, sign-out, signing via POST /sign, and the auth-shell state machine. Knows nothing about any app's data layer.",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -35,11 +35,13 @@
   "keywords": [
     "estiva",
     "estiva-id",
+    "nostr",
     "oauth",
     "pkce",
-    "nostr"
+    "signer"
   ],
   "scripts": {
+    "prebuild": "npm run build --workspace @estiva-app/protocol",
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --test test/*.test.mjs test/*.test.ts",
     "typecheck": "npm run build && tsc -p tsconfig.test.json",
@@ -47,7 +49,11 @@
   },
   "dependencies": {},
   "devDependencies": {
+    "@estiva-app/protocol": ">=0.14.0",
     "@types/node": "^24.13.3",
     "typescript": "~5.9.3"
+  },
+  "peerDependencies": {
+    "@estiva-app/protocol": ">=0.14.0"
   }
 }

package/src/index.ts

@@ -46,7 +46,7 @@
  * The thing that made it possible was not cleverness — it was that a browser API
  * an app must inject is also a browser API a test can observe.
  */
-export const IDENTITY_VERSION = '0.1.3'
+export const IDENTITY_VERSION = '0.2.1'
 
 export {
   type KeyValueStore,
@@ -81,3 +81,13 @@ export {
   SignInError,
   createEstivaId,
 } from './client.js'
+
+export {
+  type SignViaEstivaIdOptions,
+  type EstivaIdSignerOptions,
+  type SignFetchLike,
+  SignerTokenExpired,
+  SignRefused,
+  signViaEstivaId,
+  estivaIdSigner,
+} from './signer.js'

package/src/signer.ts

@@ -0,0 +1,252 @@
+/**
+ * Signing by asking Estiva ID, holding no key at all.
+ *
+ * The point of the whole seam: an app publishes as a person without ever seeing
+ * their secret. `POST /sign` takes a bearer token and an unsigned event and
+ * returns a signed one.
+ *
+ * ## Why this is identity's and not protocol's
+ *
+ * `@estiva-app/protocol` owns how an event gets its signature — the id
+ * computation, the serialization, the bytes. It owns the {@link Signer} seam and
+ * the raw-secret-key implementation of it. What it deliberately does not own is
+ * *who is allowed to ask*: the token, its renewal, and the round trip to an
+ * identity service. That is this package, and `ship/lib/nostr/signer.ts` has
+ * said so in a header comment since SHA-3 — "it is `@estiva-app/identity`'s
+ * remit — SHA-4. Until then this file is the app's copy."
+ *
+ * There were three copies until this file existed:
+ *
+ * | where | what |
+ * | --- | --- |
+ * | `ship/lib/nostr/signer.ts` | `estivaIdSigner` |
+ * | `estiva-agent/lib/nostr/signer.ts` | byte-identical to it |
+ * | `peek/src/nostr/bridge.ts` | `signViaEstivaId`, a third |
+ *
+ * Three implementations of the one call that decides who authored an event, and
+ * they had already drifted on the thing that matters most — see the guard below.
+ *
+ * ## Two exports over one round trip
+ *
+ * The consumers genuinely want different shapes, and this is not the same kind
+ * of difference as `storage` or `clientId`. Peek signs *per request* with a token
+ * it reads fresh each time (`signViaEstivaId`); Ship builds a `Signer` **once**,
+ * at module scope, which then holds a live bearer for the life of the page and
+ * renews it on a `401`. Neither can be expressed as the other without one of
+ * them getting worse, so both are here, over one implementation of the round
+ * trip and one copy of the guard.
+ *
+ * `@estiva-app/protocol` is a **peer** dependency, following `@estiva-app/interop`.
+ * Nothing here calls a protocol function — only its types are used — so the
+ * emitted `.js` imports nothing, and `dist/` keeps the property SHA-4's seam was
+ * verified by: the complete list of imports in the shipped JavaScript is
+ * `./client.js` and `./shell.js`.
+ */
+import type { SignedEvent, Signer, UnsignedEvent } from '@estiva-app/protocol'
+
+/**
+ * `fetch`, again, and for the same reason as in `client.ts` — `lib.es2022` has
+ * no such global, and this package compiles with `types: []` and no `lib: dom`
+ * so one published `.d.ts` works in every consumer (ADR 0002 §4a).
+ *
+ * Note this module needs a *slightly* wider `fetch` than `client.ts` does: it
+ * reads `text()` rather than `json()`, because `/sign`'s error bodies are not
+ * reliably JSON and the raw text is the only thing worth showing a person.
+ */
+declare const fetch: (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body: string },
+) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>
+
+/** Just the part of `fetch` this module uses. A parameter as well as a global. */
+export type SignFetchLike = typeof fetch
+
+/** Distinguishes "sign in again" from "this event was refused". */
+export class SignerTokenExpired extends Error {
+  constructor() {
+    super('The signing token has expired')
+    this.name = 'SignerTokenExpired'
+  }
+}
+
+/**
+ * A refusal that is not an expiry, **carrying the status that says which**.
+ *
+ * The status is on the error rather than only in its text because consumers
+ * classify on it and a message is not an API. Peek maps `/sign` failures into
+ * the auth shell's reason vocabulary — `403` is `identity_inactive`, an
+ * administrator's problem, while a `422` policy refusal is not — and it did that
+ * by regexing its own thrown string. A package that threw a differently worded
+ * message would have quietly collapsed every one of those into the same reason,
+ * and Peek's tests pass literal strings, so nothing would have failed.
+ */
+export class SignRefused extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'SignRefused'
+  }
+}
+
+export interface SignViaEstivaIdOptions {
+  /** Origin of the identity service, e.g. `https://id.estiva.app`. */
+  base: string
+  /** A bearer token from `POST /token`, audience-bound to this app. */
+  token: string
+  /**
+   * The pubkey the returned event **must** be authored by.
+   *
+   * Not a request. `/sign` ignores any pubkey it is handed and signs as the
+   * token's subject, always — so this is a *check*, and the reason one is needed
+   * at all is that a mismatch comes back as **HTTP 200 with a perfectly valid
+   * event authored by somebody else**. Without it the failure is invisible at
+   * the call site and surfaces later as a message attributed to the wrong
+   * person, which is not a bug anybody can debug from the symptom.
+   *
+   * Optional only because `estivaIdSigner` always supplies it and a caller with
+   * genuinely no expectation should be able to say so out loud. Supply it.
+   */
+  expectedPubkey?: string
+  fetch?: SignFetchLike
+}
+
+/**
+ * One `POST /sign`.
+ *
+ * **`/sign` refuses `kind:0` for every app, always.** Profiles belong to the
+ * identity service (PEEK-31); a refusal here is the policy working rather than
+ * something to route around.
+ *
+ * A `401` is thrown as {@link SignerTokenExpired} rather than a generic failure,
+ * because "obtain a new token" and "this event was refused" call for completely
+ * different responses from the caller and the status code is the only thing that
+ * distinguishes them.
+ */
+export async function signViaEstivaId(
+  unsigned: UnsignedEvent,
+  options: SignViaEstivaIdOptions,
+): Promise<SignedEvent> {
+  const send = options.fetch ?? fetch
+  const origin = options.base.replace(/\/+$/, '')
+
+  const response = await send(`${origin}/sign`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${options.token}`,
+    },
+    /*
+      Only the four fields that go into the signature input. The unsigned event
+      may carry a `pubkey` — Peek's NIP-98 path passes an empty one on purpose —
+      and sending it would imply `/sign` honours it, which it does not.
+    */
+    body: JSON.stringify({
+      event: {
+        kind: unsigned.kind,
+        created_at: unsigned.created_at,
+        tags: unsigned.tags,
+        content: unsigned.content,
+      },
+    }),
+  })
+
+  const text = await response.text()
+  if (response.status === 401) throw new SignerTokenExpired()
+  if (!response.ok) {
+    let reason = text.slice(0, 200)
+    try {
+      const body = JSON.parse(text) as { error?: { message?: string } }
+      reason = body.error?.message ?? reason
+    } catch {
+      // Keep the raw text. `/sign`'s error bodies are not reliably JSON, and the
+      // raw text is more use to a person than "unparseable response".
+    }
+    throw new SignRefused(response.status, `Estiva ID refused to sign kind:${unsigned.kind} — ${reason}`)
+  }
+
+  const event = (JSON.parse(text) as { event?: SignedEvent }).event
+  if (!event) throw new Error('POST /sign returned no event')
+
+  if (options.expectedPubkey && event.pubkey !== options.expectedPubkey) {
+    throw new Error(
+      `POST /sign returned an event authored by ${event.pubkey}, expected ${options.expectedPubkey}. ` +
+        'That token belongs to a different identity — refusing to publish under the wrong author.',
+    )
+  }
+
+  return event
+}
+
+export interface EstivaIdSignerOptions {
+  /** Origin of the identity service, e.g. `https://id.estiva.app`. */
+  base: string
+  /** The pubkey the token was issued for — `sub` in the JWT. */
+  pubkey: string
+  /** A bearer token from `POST /token`, audience-bound to this app. */
+  token: string
+  /**
+   * Renew the token, once, when `/sign` says it has expired (PEEK-108).
+   *
+   * Optional: without it a `401` surfaces as {@link SignerTokenExpired} for the
+   * caller to deal with, exactly as before. With it, an expiry is invisible —
+   * which matters more than it used to, because access tokens live ten minutes
+   * rather than an hour, so a session of any length crosses one.
+   *
+   * Returning `null` means renewal failed and the expiry is real.
+   *
+   * Pass `client.refreshAccessToken` and nothing else: it coalesces concurrent
+   * callers, and a refresh token is single-use with a replay read as theft.
+   */
+  renew?: () => Promise<string | null>
+  fetch?: SignFetchLike
+}
+
+/**
+ * A {@link Signer} that signs by asking Estiva ID.
+ *
+ * Holds the live bearer, so a renewal replaces it for every later signature
+ * rather than being rediscovered on each one.
+ */
+export function estivaIdSigner({ base, pubkey, token, renew, fetch: send }: EstivaIdSignerOptions): Signer {
+  let bearer = token
+
+  return {
+    pubkey,
+    kind: 'estiva-id',
+    async sign(unsigned) {
+      const once = (auth: string) =>
+        signViaEstivaId(unsigned, {
+          base,
+          token: auth,
+          // The guard, unconditionally. Ship's copy of this signer never had it
+          // and Peek's `signViaEstivaId` did, which is exactly the drift three
+          // copies produce: the app that publishes every issue, comment and
+          // status change was the one that could not tell it had signed as
+          // somebody else. SHA-4's Traps section says both must keep it.
+          expectedPubkey: pubkey,
+          ...(send ? { fetch: send } : {}),
+        })
+
+      try {
+        return await once(bearer)
+      } catch (error) {
+        /*
+          Renew once and retry, never twice.
+
+          A second 401 after a successful renewal is not an expiry — it is a
+          token the service will not accept, and retrying that in a loop is how
+          one refused signature becomes a hot loop against the identity service.
+          Anything that is not an expiry is rethrown untouched, so a wrong-author
+          refusal is never mistaken for something a new token would fix.
+        */
+        if (!(error instanceof SignerTokenExpired) || !renew) throw error
+        const renewed = await renew()
+        if (!renewed) throw error
+        bearer = renewed
+        return await once(bearer)
+      }
+    },
+  }
+}