@estiva-app/identity 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# @estiva-app/identity
+
+## 0.1.0 — 2026-08-27
+
+First release. SHA-4, extracted during REW-2.
+
+**No wire behaviour.** This package publishes no events. It obtains and holds a
+token; `@estiva-app/protocol` is what turns intent into bytes.
+
+The PKCE flow, token storage and validity, silent renewal, sign-out, the returnTo
+and shell-reason vocabulary, and the auth-shell state machine. Extracted from
+Peek, which was ahead of Ship: Ship had no shell-reason vocabulary at all, so
+this is an upgrade for Ship rather than a port of it.
+
+### What is deliberately not here
+
+- **Any app's data layer.** Peek's `useEstivaIdAuth.ts` — the
+  `ConvexProviderWithAuth` adapter — stays in Peek. If it were here, Ship and
+  every future app would inherit a Convex dependency to work around. Ship needing
+  no adapter at all is the test that the line held, and CI enforces it.
+- **The shell's rendering.** A full-page surface each app will want its own of.
+  Shared is the state machine and the reason vocabulary, which is where the
+  expensive mistakes live — and keeping components out also keeps this package
+  clear of `@estiva-app/ui`, whose entry would trigger ADR 0002 §2's rule about
+  folding `ui` back into the foundation repo.
+
+### Five behaviours that are each an incident, not a nicety
+
+Every one is covered by a test that travelled with the code:
+
+- **`clearSession` must not touch a sign-in in flight (PEEK-167).** The verifier,
+  state and returnTo belong to an authorization request currently in the air.
+  Clearing them on somebody else's schedule destroys a sign-in that is still
+  happening, and the failure surfaces as an `exchange_failed` for a code that was
+  never presented to `/token` — so the identity service has no record of it.
+- **The silent guard is marked synchronously with those writes**, not next to the
+  navigation. `codeChallenge` awaits a digest in between, and that window is long
+  enough for a second boot to decide to probe as well.
+- **`token_rejected` never reads as "session expired".** Telling somebody their
+  session expired when their token was refused for a configuration fault sends
+  them to re-authenticate against a wall.
+- **Refresh tokens are single-use and a replay is treated as theft.** The stored
+  token is cleared when the grant is *refused*, and deliberately not when the
+  network is merely unreachable — a flaky connection must not sign somebody out.
+- **Clearing the local token is not signing out (PEEK-122).** The
+  `estiva_id_session` cookie on the identity origin survives it, so the next
+  silent probe puts the person straight back in. Real sign-out navigates to
+  `/logout`.
+
+### A prediction this package falsified
+
+The expectation on record, from having just done `@estiva-app/protocol`, was that
+identity could not follow ADR 0002 §4a as cleanly — that being browser-shaped
+throughout, it would need `lib: dom` and a looser rule.
+
+It did not need either. Details in the README; the short version is that a browser
+API an app must inject is also a browser API a test can observe.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Estiva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @estiva-app/identity
+
+Signing in with Estiva ID: authorization code + PKCE, token storage, silent
+renewal, sign-out, and the auth-shell state machine.
+
+```bash
+npm install @estiva-app/identity
+```
+
+No runtime dependencies. CI enforces that.
+
+## The seam this package exists for
+
+**In:** everything that decides *whether somebody is signed in* and *what to say
+when they are not*.
+
+**Not in: any app's data layer.** `peek-app/src/auth/useEstivaIdAuth.ts` is the
+adapter `ConvexProviderWithAuth` reads, and it stays in Peek. If it were here,
+Ship and every future app would inherit a Convex dependency to work around —
+which is precisely the failure SHA-4's sequencing exists to avoid.
+
+**Ship needing no adapter at all is the test that the line held.** It hands the
+token straight to its relay client.
+
+**Not in: the shell's rendering.** A full-page surface each app wants its own of.
+Shared is the state machine and the reason vocabulary. That also keeps this
+package clear of `@estiva-app/ui` — ADR 0002 §2 names identity depending on `ui`
+as the trigger that folds `ui` back into the foundation repo, and that should be
+a decision somebody makes rather than one a sign-in screen makes by accident.
+
+## Every difference between the consumers is a parameter
+
+The package is a factory, not a module of free functions, because Peek and Ship
+genuinely differ on every one of these — and hardcoding any would have made the
+package come out Peek-shaped, which is the whole risk SHA-4 names.
+
+| injected | Peek | Ship |
+| --- | --- | --- |
+| `clientId` | `estiva-peek` | `estiva-ship` |
+| `redirectUri` | a fixed `/auth/callback` | its current pathname — Ship routes on `location.hash` |
+| `storage` | `sessionStorage`, which dies with the tab | `localStorage` |
+| `keyPrefix` | `peek.estivaId` | `ship.estiva-id` |
+| `navigate` | the one genuinely untestable act, so it is observable |  |
+
+**Do not unify `storage`.** NIP-RS read-state slots (CRO-4) must survive a restart
+and belong in `localStorage`; an access token does not. Different lifetimes,
+different homes.
+
+An app instantiates once and re-exports its own names, so call sites do not churn:
+
+```ts
+const client = createEstivaId({
+  base: ESTIVA_ID_ORIGIN,
+  clientId: 'estiva-peek',
+  redirectUri: () => `${window.location.origin}/auth/callback`,
+  storage: () => (typeof window === 'undefined' ? null : window.sessionStorage),
+  keyPrefix: 'peek.estivaId',
+  navigate: (url) => window.location.assign(url),
+})
+export const { validToken, beginSignIn, completeSignIn, beginSignOut } = client
+```
+
+## The prediction this package falsified
+
+Before starting, the expectation on the ticket was that identity **could not**
+follow ADR 0002 §4a as cleanly as `@estiva-app/protocol` did — that being
+browser-shaped throughout, it would need `lib: dom`, and that the ADR would need
+amending to say so.
+
+That was wrong, and it is worth saying why rather than quietly not mentioning it:
+
+- `crypto`, `btoa`, `TextEncoder`, `URL`, `URLSearchParams`, `fetch` and `console`
+  are declared inside the modules that use them and read inside function bodies.
+- The DOM's `Storage` became a local `KeyValueStore` interface. `sessionStorage`,
+  `localStorage` and a plain object all satisfy it structurally, and the published
+  declarations name no ambient type.
+- Navigation is a **required** `navigate` callback rather than a `location` reach.
+
+So the package builds with `types: []` and no `lib: dom`, exactly as `protocol`
+does, and a test can import it with every browser global deleted. CI asserts both.
+
+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** — the seams §4a forces
+and the seams a test wants are the same seams. Worth remembering before assuming
+the next browser-shaped package needs an exemption.
+
+`@estiva-app/ui` is still the counter-example: it ships `.d.ts` files naming
+`HTMLButtonElement`, and gets away with it only because both its consumers are
+browser apps.
+
+## Releasing
+
+```bash
+git tag identity@0.1.1 && git push origin identity@0.1.1
+```
+
+The **first** publish is manual and once-ever, because a trusted publisher is
+configured on a package that already exists — ADR 0002 §4c, §7. Every release
+after it is a tag.

package/dist/client.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Signing in with Estiva ID — authorization code + PKCE.
+ *
+ * The app does not hold a password or a key. It sends the person to the identity
+ * service and gets back a token whose `sub` is their Nostr pubkey.
+ *
+ * ## Why a redirect rather than a fetch
+ *
+ * `POST /token` is reachable cross-origin, but the *session* that authorises the
+ * redirect is a `SameSite=Lax` cookie on the identity origin. Lax cookies ride
+ * top-level navigations and nothing else, so the only way to prove who you are
+ * is to actually go there. That is deliberate on their side (PEEK-90): the origin
+ * holding every custodied key does not relax its cookie or send
+ * `Access-Control-Allow-Credentials`.
+ *
+ * **A hidden iframe does not work**, and the reason is the same property: `Lax`
+ * withholds the cookie from anything that is not a top-level navigation. The
+ * refresh-token grant exists because of this. Do not "simplify" it back.
+ *
+ * ## The bits that must match exactly
+ *
+ * `redirect_uri` is compared **exact-string** against the app's registered list —
+ * a trailing slash is a different URI and gets a 400 before anything else
+ * happens. An identity provider that prefix-matched would be an open redirector
+ * handing out authorization codes.
+ *
+ * The request body is **camelCase JSON** (`codeVerifier`, not `code_verifier`)
+ * while the response is snake_case (`access_token`). That is genuinely the
+ * contract, not a typo — see `docs/API.md` in estiva-id.
+ *
+ * ## Everything is injected, and each injection is a real difference
+ *
+ * This is a factory rather than a module of free functions because the two
+ * consumers genuinely differ, and hardcoding either would have made the package
+ * come out shaped like whichever app it was extracted from:
+ *
+ * - **`clientId`** — `estiva-peek` and `estiva-ship` are separate rows in
+ *   `app_credentials` with separate `redirectUris` and separate kind ceilings.
+ * - **`redirectUri`** — Peek registers a fixed `/auth/callback`; Ship routes on
+ *   `location.hash` and registers its current pathname. Neither is more correct.
+ * - **`storage`** — Peek keeps its token in `sessionStorage`, which dies with the
+ *   tab and keeps a bearer token off a shared machine's disk. Ship uses
+ *   `localStorage`. **Do not unify this**: NIP-RS slots (CRO-4) must survive a
+ *   restart and belong in `localStorage`, while an access token does not.
+ *   Different lifetimes, different homes.
+ * - **`keyPrefix`** — so two apps on one origin cannot read each other's keys.
+ * - **`navigate`** — the one genuinely untestable act. Injected so a test can
+ *   observe where the flow *would* go.
+ */
+import { type KeyValueStore, type ShellReason } from './shell.js';
+/** Just enough of `fetch` to redeem a code. A parameter as well as a global. */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export interface EstivaIdConfig {
+    /** Origin of the identity service, e.g. `https://id.estiva.app`. */
+    base: string;
+    /** This app's `client_id` row in `app_credentials`. Never defaulted. */
+    clientId: string;
+    /**
+     * Where Estiva ID sends people back to. Must match a registered entry
+     * **exactly** — a trailing slash is a refused sign-in.
+     */
+    redirectUri: () => string;
+    /** See the note on storage above. Returns null outside a browser. */
+    storage: () => KeyValueStore | null;
+    /** Namespaces this app's keys, e.g. `peek.estivaId`. */
+    keyPrefix: string;
+    /** Defaults to the runtime's `location.assign`-equivalent via `navigate`. */
+    navigate?: (url: string) => void;
+    now?: () => number;
+    fetch?: FetchLike;
+}
+export interface StoredToken {
+    accessToken: string;
+    /** Epoch ms. Derived from `expires_in` at receipt, not sent by the server. */
+    expiresAt: number;
+    pubkey: string;
+    /**
+     * The credential that renews the one above without a redirect (PEEK-108).
+     *
+     * Absent when Estiva ID issued none — a deployment predating the grant. The
+     * app then behaves exactly as it did before, which is what lets the two sides
+     * ship independently.
+     *
+     * **Single-use.** Estiva ID rotates it on every redemption and treats a replay
+     * as evidence of theft, revoking the whole chain. So it is replaced, never
+     * kept alongside its successor.
+     */
+    refreshToken?: string;
+}
+export declare class SignInError extends Error {
+}
+export interface EstivaIdClient {
+    redirectUri: () => string;
+    codeChallenge: (verifier: string) => Promise<string>;
+    beginSignIn: (returnTo: string, options?: {
+        silent?: boolean;
+    }) => Promise<void>;
+    completeSignIn: (search: string) => Promise<{
+        token: StoredToken;
+        returnTo: string;
+    }>;
+    refreshAccessToken: () => Promise<StoredToken | null>;
+    storedToken: () => StoredToken | null;
+    validToken: (now?: number) => StoredToken | null;
+    hasSession: () => boolean;
+    currentAccessToken: () => string | undefined;
+    beginSignOut: () => void;
+    clearSession: () => void;
+    hasPendingSignIn: () => boolean;
+    clearPendingSignIn: () => void;
+    takeReturnTo: () => string | null;
+    stashShellReason: (reason: ShellReason) => void;
+    takeShellReason: () => ShellReason | null;
+}
+export declare function createEstivaId(config: EstivaIdConfig): EstivaIdClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAyB,MAAM,YAAY,CAAA;AAuBxF,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG,CACtB,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,OAAO,CAAC,CAAA;CAAE,CAAC,CAAA;AAIvE,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,WAAW,EAAE,MAAM,MAAM,CAAA;IACzB,qEAAqE;IACrE,OAAO,EAAE,MAAM,aAAa,GAAG,IAAI,CAAA;IACnC,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAA;IACjB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,qBAAa,WAAY,SAAQ,KAAK;CAAG;AASzC,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,MAAM,CAAA;IACzB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACpD,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAChF,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACrF,kBAAkB,EAAE,MAAM,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;IACrD,WAAW,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;IACrC,UAAU,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,WAAW,GAAG,IAAI,CAAA;IAChD,UAAU,EAAE,MAAM,OAAO,CAAA;IACzB,kBAAkB,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC5C,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,gBAAgB,EAAE,MAAM,OAAO,CAAA;IAC/B,kBAAkB,EAAE,MAAM,IAAI,CAAA;IAC9B,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACjC,gBAAgB,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAA;IAC/C,eAAe,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;CAC1C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CA4WrE"}