@flow-industries/id 0.23.4 → 0.24.1

package/README.md

@@ -21,6 +21,82 @@ rotated so local session creation keeps working after environment changes.
 It also refuses to start when migrations fail instead of serving against a
 partially migrated schema.
 
+### AT Protocol identity
+
+Bluesky and other AT Protocol accounts can sign in to Flow ID or connect to an
+existing account. Flow user IDs remain stable; the provider DID identifies the
+connection. New accounts do not need an email, passkey, or wallet to enroll.
+
+Set `ATPROTO_PUBLIC_URL`, `ATPROTO_PRIVATE_KEY` (an ES256 private JWK with a stable
+`kid`), and `ATPROTO_STORAGE_KEY` (a base64-encoded 32-byte encryption key) to
+enable the integration. Leave all three unset to disable it. Production uses
+HTTPS client metadata at `/api/auth/atproto/client-metadata.json` and public keys
+at `/api/auth/atproto/jwks.json`. Provider tokens and DPoP keys are encrypted in
+Postgres and stay on the server. Back up the storage key with the database;
+changing it requires re-encrypting stored credentials.
+
+For local OAuth, set `ATPROTO_PUBLIC_URL=http://127.0.0.1:8183` and launch
+`./dev.sh 8180`. The hosted sign-in page uses `http://localhost:8183` and the
+launcher sets the WebAuthn relying party to `localhost`. Use the printed URLs;
+existing passkeys remain bound to their original relying party.
+
+Without an email provider configured, the local launcher also prints sign-in
+codes in the browser console. This requires development mode, the launcher's
+`FLOW_DEV_OTP_CONSOLE=1` opt-in, and a loopback issuer; the API then binds only to
+`127.0.0.1`. Production responses never include these codes.
+
+AT Protocol requires an IP loopback callback URI. The development landing server
+redirects loopback GET requests to its fixed localhost origin before handling
+them, retaining the callback query so OAuth resumes with the same browser cookies
+and session storage as sign-in. The SDK still exchanges the code using the
+registered IP callback URI. If that port block is occupied, update
+`ATPROTO_PUBLIC_URL` to the selected landing port and restart. Production clients
+use HTTPS metadata and authenticate with the configured signing key.
+
+Provider sign-in resumes the bound `/authorize` transaction. Flow installs a
+first-party session, then returns the existing one-use PKCE code to the app.
+Account linking returns to `/account`; no provider or Flow tokens travel in
+redirect URLs or window messages.
+
+The account connection view reads saved identities and credentials locally. It
+does not refresh provider tokens or resolve handles on page load; reconnect
+performs a new provider authorization when access needs to be restored.
+
+### Connected accounts
+
+Better Auth owns the shared `account` model. External identities are keyed by
+`providerId` and `accountId`, and link to the canonical Flow `userId`. For AT
+Protocol these values are `atproto` and the verified DID. Handles are display
+metadata, never an identity key. A Flow account can connect different providers
+without adding provider-specific identity tables.
+Provider IDs identify a trusted provider configuration: separate OIDC issuers
+must use separate IDs, even if both run the same identity-server software.
+
+Provider credentials and temporary authorization state live in the encrypted,
+provider-scoped `oauth_session` and `oauth_state` stores. The AT SDK uses an
+adapter over those stores; its DPoP and discovery behavior stays within the AT
+integration. Provider tokens never become Flow session tokens.
+
+Better Auth supports built-in social providers and its Generic OAuth plugin.
+Flow currently uses version 1.4.17, whose default OAuth enrollment requires an
+email and creates its own sessions. A new provider must supply a verified stable
+subject to Flow's shared account enrollment, then use Flow's audience-bound
+session issuance. Register usable sign-in providers explicitly; arbitrary
+account rows do not count as recovery methods. No new identity table is needed.
+
+Automatic email-based account linking is disabled. Disconnect through Flow's
+account controls so credential cleanup and last-sign-in-method checks run in
+one transaction; the stock Better Auth unlink endpoint is blocked. Its account
+listing remains available and excludes credentials.
+
+Migration `0040` preserves existing AT links and encrypted sessions, then removes
+the earlier AT-only tables. It invalidates in-flight authorization state, so
+unfinished attempts must restart. Deploy the complete revised Auth stack before
+enabling AT production configuration. After this migration, the intermediate
+AT-only builds from PRs #170–#172 are not rollback targets; use the pre-AT main
+build or a compatible forward fix. Existing pre-AT Flow user/session writes
+remain supported.
+
 **npm:** [`@flow-industries/id`](https://www.npmjs.com/package/@flow-industries/id)
 
 ## Installation

package/dist/sdk/browser-contract.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+export declare const BROWSER_FLOW_TTL_MS: number;
 export declare const browserSigningSchema: z.ZodObject<{
     signature: z.ZodObject<{
         r: z.ZodString;

package/dist/sdk/browser-contract.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+export const BROWSER_FLOW_TTL_MS = 24 * 60 * 60 * 1000;
 export const browserSigningSchema = z.object({
     signature: z.object({
         r: z.string().regex(/^\d+$/),

package/dist/sdk/browser-session-route.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { browserSigningSchema } from "./browser-contract";
+import { BROWSER_FLOW_TTL_MS, browserSigningSchema } from "./browser-contract";
 import { clearCookieString, cookieNamesFor, parseCookieHeader, serializeCookie, } from "./cookies";
 import { fetchIssuerApi, resolveIssuerApiUrl } from "./issuer-api";
 import { claimsToUser, sessionCookies } from "./session-core";
@@ -110,14 +110,14 @@ export async function startBrowserSession(request, audience, issuerUrl, body, ap
         state,
         verifier,
         returnTo,
-        expires: Date.now() + 600_000,
+        expires: Date.now() + BROWSER_FLOW_TTL_MS,
     })));
     return reply({
         loginId: state,
         authorizeUrl: `${issuerUrl}/authorize?transaction=${transaction}`,
     }, 200, [
         serializeCookie(cookieName(audience, state), pending, {
-            maxAge: 600,
+            maxAge: BROWSER_FLOW_TTL_MS / 1000,
             secure: audience.startsWith("https:"),
         }),
     ]);

package/dist/sdk/client/atproto.d.ts

@@ -0,0 +1,5 @@
+import type { AtprotoCompletion, AtprotoStartRequest, AtprotoStatus } from "../types";
+export declare function getAtprotoStatus(signal?: AbortSignal): Promise<AtprotoStatus>;
+export declare function unlinkAtproto(expectedUserId: string): Promise<void>;
+export declare function connectAtproto(request: AtprotoStartRequest, signal: AbortSignal): Promise<void>;
+export declare function completeAtproto(): Promise<AtprotoCompletion>;

package/dist/sdk/client/atproto.js

@@ -0,0 +1,49 @@
+async function readResponse(response) {
+    const body = await response.json();
+    if (!response.ok)
+        throw new Error(body.message ??
+            body.error ??
+            "Could not connect your AT Protocol account.");
+    // SAFETY: the caller names the payload returned by the same-origin Flow endpoint.
+    return body;
+}
+export async function getAtprotoStatus(signal) {
+    return readResponse(await fetch("/api/auth/atproto/status", { credentials: "include", signal }));
+}
+export async function unlinkAtproto(expectedUserId) {
+    await readResponse(await fetch("/api/auth/atproto/unlink", {
+        method: "POST",
+        credentials: "include",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ expectedUserId }),
+    }));
+}
+const completionKey = "flow.atproto.completion";
+export async function connectAtproto(request, signal) {
+    signal.throwIfAborted();
+    const result = await readResponse(await fetch("/api/auth/atproto/start", {
+        method: "POST",
+        credentials: "include",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(request),
+        signal,
+    }));
+    signal.throwIfAborted();
+    sessionStorage.setItem(completionKey, result.completionToken);
+    window.location.assign(result.url);
+}
+let completion = null;
+export function completeAtproto() {
+    if (completion)
+        return completion;
+    const completionToken = sessionStorage.getItem(completionKey);
+    if (!completionToken)
+        return Promise.reject(new Error("Sign-in expired. Please try again."));
+    completion = fetch("/api/auth/atproto/complete", {
+        method: "POST",
+        credentials: "include",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ completionToken }),
+    }).then((readResponse));
+    return completion;
+}

package/dist/sdk/client/create-flow.js

@@ -1,3 +1,4 @@
+import { BROWSER_FLOW_TTL_MS } from "../browser-contract";
 import { DEFAULT_SESSION_PATH, isLocalHostname, resolveIdHost, } from "../id-host";
 import { isExpiring } from "../token-expiry";
 import { createDialogHost } from "./dialog-host";
@@ -385,7 +386,7 @@ export function createFlow(options = {}) {
         if (preparation)
             await idb.set(`flow.pendingAccessKey.${result.loginId}`, {
                 preparation,
-                expires: Date.now() + 600_000,
+                expires: Date.now() + BROWSER_FLOW_TTL_MS,
             });
         window.location.assign(result.authorizeUrl);
         return new Promise((_resolve, reject) => {

package/dist/sdk/db/handle.d.ts

@@ -0,0 +1,11 @@
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import type * as schema from "./schema";
+/**
+ * Any pg-dialect drizzle handle over the app schema — postgres-js in the
+ * server, PGlite in the tests.
+ *
+ * Core logic takes this as a parameter instead of importing the `db` singleton,
+ * which requires DATABASE_URL at import time and so cannot be exercised without
+ * a Postgres server. Type-only, so importing it never pulls the singleton in.
+ */
+export type AppDb = PgDatabase<PgQueryResultHKT, typeof schema>;