@flow-industries/id 0.26.3 → 0.26.5

package/README.md

@@ -23,6 +23,33 @@ partially migrated schema.
 
 ### AT Protocol identity
 
+Consumers discover the signed-in user's current PDS through
+`await flow.atproto.resolve({ freshness: "cached" })`. Use `"refresh"` after an
+endpoint or authorization failure, and call `flow.atproto.invalidate()` after
+identity or migration events. Flow account switches, logout and the first-party
+linking helpers invalidate automatically. Invalidation forces the next request
+to refresh. Discovery uses the configured Auth host, cookie or Flow bearer
+session, and canonical user ID; it never provisions an account.
+
+The result includes the DID, verified display handle (or null), current PDS
+origin, hosting ownership, lifecycle and authorization status. DID documents
+are authoritative for the endpoint. No OAuth tokens or private keys are
+returned. `connected` indicates an unexpired stored grant whose audience and
+issuer match public resource metadata; it does not prove that a remote grant
+has not since been revoked. Writes must obtain fresh AT OAuth authorization,
+and must not forward old credentials to a migrated host or replay mutations
+with unknown outcomes. `AtprotoRequestError.code` distinguishes sign-in,
+missing identity, pending or failed provisioning, account changes, unsupported
+DID methods, invalid identity and unavailable resolution.
+
+`ATPROTO_MANAGED_PDS_ORIGINS` is an optional comma-separated list of public
+HTTPS PDS origins owned by Flow, used only to classify current hosting.
+`ATPROTO_RESOLUTION_TTL_MS` enables a server metadata cache keyed by DID and
+mapping version, bounded to five minutes; unset or invalid values disable
+caching. Authorization status is checked separately on each request. A cached
+authorization failure forces one fresh DID resolution. Public discovery works
+without OAuth credential configuration and reports `reconnect_required`.
+
 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.
@@ -223,3 +250,14 @@ still need complete request/response descriptions and generated client coverage
 before the full HTTP contract work is complete.
 
 Server deployments may set `FLOW_ID_API_URL` to a trusted internal HTTP(S) origin for API and JWKS requests, or pass `apiUrl` to server session/verification helpers. `issuerUrl` remains the public JWT issuer and browser navigation origin. The transport URL must contain no credentials, path, query, or fragment.
+
+PDS discovery requires explicit nonnegative integer budgets in
+`ATPROTO_RESOLUTION_USER_HOURLY_CAP` and
+`ATPROTO_RESOLUTION_GLOBAL_HOURLY_CAP`. Unset, invalid or zero budgets refuse
+outbound discovery with HTTP 429 and retryable `RESOLUTION_UNAVAILABLE`. Every discovery
+request, including cached reads and forced refreshes, consumes durable
+per-user and fleet-wide hourly admission before any provider request. Failed
+outbound attempts retain admission consumption; counters use the existing
+bounded verification retention and canonical account erasure mechanism.
+These caps bound request admission across replicas; operators must choose
+budgets appropriate to replica count, outbound latency and capacity.

package/contracts/v1/sdk-exports.json

@@ -92,6 +92,31 @@
         "type": false,
         "value": true
       },
+      {
+        "name": "AtprotoApi",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "AtprotoRequestError",
+        "type": true,
+        "value": true
+      },
+      {
+        "name": "AtprotoResolution",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "AtprotoResolutionFailure",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "AtprotoResolveOptions",
+        "type": true,
+        "value": false
+      },
       {
         "name": "BrowserAccount",
         "type": true,
@@ -142,6 +167,11 @@
         "type": false,
         "value": true
       },
+      {
+        "name": "createAtprotoApi",
+        "type": false,
+        "value": true
+      },
       {
         "name": "createDialogHost",
         "type": false,
@@ -167,6 +197,11 @@
         "type": false,
         "value": true
       },
+      {
+        "name": "createNoteTransport",
+        "type": false,
+        "value": true
+      },
       {
         "name": "createProfileButton",
         "type": false,
@@ -222,6 +257,11 @@
         "type": false,
         "value": true
       },
+      {
+        "name": "evaluatePasskeyPrf",
+        "type": false,
+        "value": true
+      },
       {
         "name": "fieldsCoveredBySubjects",
         "type": false,
@@ -317,6 +357,11 @@
         "type": false,
         "value": true
       },
+      {
+        "name": "getConnectedPasskey",
+        "type": false,
+        "value": true
+      },
       {
         "name": "getFlow",
         "type": false,
@@ -397,6 +442,46 @@
         "type": false,
         "value": true
       },
+      {
+        "name": "NoteBlob",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "NoteCollection",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "NoteOperation",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "NoteRecord",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "NoteResponses",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "NoteStoredRecord",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "NoteTransportError",
+        "type": true,
+        "value": true
+      },
+      {
+        "name": "NoteVaultHeader",
+        "type": true,
+        "value": false
+      },
       {
         "name": "NotificationCounts",
         "type": true,
@@ -432,6 +517,16 @@
         "type": true,
         "value": false
       },
+      {
+        "name": "PasskeyPrfError",
+        "type": true,
+        "value": true
+      },
+      {
+        "name": "PasskeyPrfOptions",
+        "type": true,
+        "value": false
+      },
       {
         "name": "ProfileButtonHandle",
         "type": true,

package/dist/sdk/caller.d.ts

@@ -0,0 +1,29 @@
+import type { AppDb } from "./db/handle";
+import type { SessionUser } from "./types";
+/**
+ * Caller-identity core, shared by the dialog-facing routes and the tests. Takes
+ * the drizzle handle as a parameter (postgres-js in the server, PGlite in
+ * tests) instead of importing the singleton, which requires DATABASE_URL at
+ * import time. The singleton-bound entry point is `resolveCaller` in
+ * `routes/caller.ts`.
+ */
+/**
+ * The user behind a dialog request, and the better-auth session row that
+ * authenticated it — null when the caller presented an access JWT instead,
+ * since a bearer holds no session row.
+ */
+/** The session row as callers read it: opaque beyond the fields session-view names. */
+export type CallerSession = {
+    id: string;
+    audience?: string | null;
+};
+export type Caller = {
+    user: SessionUser;
+    session: CallerSession | null;
+};
+/**
+ * Reads the user a verified bearer's `sub` names, in the shape better-auth puts
+ * on `session.user`. Null when the subject no longer exists — a token for a
+ * deleted account is unauthorized, not a caller with an empty profile.
+ */
+export declare function loadCallerUser(dbi: AppDb, userId: string): Promise<SessionUser | null>;

package/dist/sdk/caller.js

@@ -0,0 +1,37 @@
+import { eq } from "drizzle-orm";
+import * as schema from "./db/schema";
+import { sessionUserOf } from "./session-view";
+/**
+ * The columns better-auth puts on `session.user` (base fields plus the
+ * configured `additionalFields`), so a bearer-authenticated caller reads back
+ * the same user shape a cookie-authenticated one does. `sessionEpoch` is
+ * deliberately absent: it is an internal revocation lever, not profile data.
+ */
+const USER_COLUMNS = {
+    id: schema.user.id,
+    name: schema.user.name,
+    username: schema.user.username,
+    email: schema.user.email,
+    emailVerified: schema.user.emailVerified,
+    image: schema.user.image,
+    bio: schema.user.bio,
+    isGuest: schema.user.isGuest,
+    role: schema.user.role,
+    walletAddress: schema.user.walletAddress,
+    subscribedToNews: schema.user.subscribedToNews,
+    createdAt: schema.user.createdAt,
+    updatedAt: schema.user.updatedAt,
+};
+/**
+ * Reads the user a verified bearer's `sub` names, in the shape better-auth puts
+ * on `session.user`. Null when the subject no longer exists — a token for a
+ * deleted account is unauthorized, not a caller with an empty profile.
+ */
+export async function loadCallerUser(dbi, userId) {
+    const [user] = await dbi
+        .select(USER_COLUMNS)
+        .from(schema.user)
+        .where(eq(schema.user.id, userId))
+        .limit(1);
+    return user ? sessionUserOf(user) : null;
+}

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

@@ -0,0 +1,8 @@
+import type { AtprotoApi, AtprotoResolutionFailure } from "../types/atproto";
+export declare class AtprotoRequestError extends Error {
+    readonly code: AtprotoResolutionFailure;
+    readonly retryable: boolean;
+    constructor(code: AtprotoResolutionFailure, retryable?: boolean);
+}
+/** Identity changes and migration completion should invalidate before another discovery. */
+export declare function createAtprotoApi(host: string, getToken: () => Promise<string | null>, getUserId: () => string | null): AtprotoApi;

package/dist/sdk/client/atproto-resolver.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+const failureSchema = z.enum([
+    "SIGN_IN_REQUIRED",
+    "NO_AT_IDENTITY",
+    "PROVISIONING_PENDING",
+    "PROVISIONING_FAILED",
+    "ACCOUNT_CHANGED",
+    "UNSUPPORTED_DID_METHOD",
+    "IDENTITY_INVALID",
+    "RESOLUTION_UNAVAILABLE",
+]);
+const resolutionSchema = z.object({
+    flowUserId: z.string(),
+    did: z.string(),
+    handle: z.string().nullable(),
+    pdsUrl: z.url(),
+    hosting: z.enum(["flow", "external"]),
+    lifecycle: z.enum(["active", "suspended", "migrated", "deletion_pending"]),
+    authorization: z.enum(["connected", "reconnect_required"]),
+    resolvedAt: z.iso.datetime(),
+    expiresAt: z.iso.datetime(),
+    identityVersion: z.string(),
+});
+export class AtprotoRequestError extends Error {
+    code;
+    retryable;
+    constructor(code, retryable = false) {
+        super(code);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = "AtprotoRequestError";
+    }
+}
+/** Identity changes and migration completion should invalidate before another discovery. */
+export function createAtprotoApi(host, getToken, getUserId) {
+    let generation = 0;
+    let dirty = false;
+    return {
+        invalidate() {
+            generation++;
+            dirty = true;
+        },
+        async resolve(options = {}) {
+            options.signal?.throwIfAborted();
+            const userId = getUserId();
+            if (!userId)
+                throw new AtprotoRequestError("SIGN_IN_REQUIRED");
+            const requestGeneration = generation;
+            const unchanged = () => {
+                if (generation !== requestGeneration || getUserId() !== userId)
+                    throw new AtprotoRequestError("ACCOUNT_CHANGED");
+            };
+            const token = await getToken();
+            unchanged();
+            const headers = new Headers({ "X-Flow-User-Id": userId });
+            if (token)
+                headers.set("Authorization", `Bearer ${token}`);
+            let response;
+            try {
+                response = await fetch(`${host}/api/atproto/resolve?freshness=${dirty ? "refresh" : (options.freshness ?? "cached")}`, { headers, credentials: "include", signal: options.signal });
+            }
+            catch {
+                options.signal?.throwIfAborted();
+                unchanged();
+                throw new AtprotoRequestError("RESOLUTION_UNAVAILABLE", true);
+            }
+            unchanged();
+            const body = await response.json().catch(() => null);
+            options.signal?.throwIfAborted();
+            unchanged();
+            if (!response.ok) {
+                const parsed = z.object({ code: failureSchema }).safeParse(body);
+                const code = parsed.success
+                    ? parsed.data.code
+                    : "RESOLUTION_UNAVAILABLE";
+                throw new AtprotoRequestError(code, ["RESOLUTION_UNAVAILABLE", "PROVISIONING_PENDING"].includes(code));
+            }
+            const parsed = resolutionSchema.safeParse(body);
+            if (!parsed.success)
+                throw new AtprotoRequestError("IDENTITY_INVALID");
+            if (parsed.data.flowUserId !== userId)
+                throw new AtprotoRequestError("ACCOUNT_CHANGED");
+            dirty = false;
+            return parsed.data;
+        },
+    };
+}

package/dist/sdk/client/atproto.js

@@ -1,3 +1,4 @@
+import { getFlow } from "./create-flow";
 async function readResponse(response) {
     const body = await response.json();
     if (!response.ok)
@@ -17,6 +18,7 @@ export async function unlinkAtproto(expectedUserId) {
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ expectedUserId }),
     }));
+    getFlow()?.atproto.invalidate();
 }
 const completionKey = "flow.atproto.completion";
 export async function connectAtproto(request, signal) {
@@ -30,6 +32,7 @@ export async function connectAtproto(request, signal) {
     }));
     signal.throwIfAborted();
     sessionStorage.setItem(completionKey, result.completionToken);
+    getFlow()?.atproto.invalidate();
     window.location.assign(result.url);
 }
 let completion = null;
@@ -44,6 +47,11 @@ export function completeAtproto() {
         credentials: "include",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ completionToken }),
-    }).then((readResponse));
+    })
+        .then((readResponse))
+        .then((result) => {
+        getFlow()?.atproto.invalidate();
+        return result;
+    });
     return completion;
 }

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

@@ -1,6 +1,7 @@
 import { BROWSER_FLOW_TTL_MS } from "../browser-contract";
 import { DEFAULT_SESSION_PATH, isLocalHostname, resolveIdHost, } from "../id-host";
 import { isExpiring } from "../token-expiry";
+import { createAtprotoApi } from "./atproto-resolver";
 import { createDialogHost } from "./dialog-host";
 import { idb } from "./idb";
 import { createRoomsApi } from "./rooms";
@@ -510,6 +511,14 @@ export function createFlow(options = {}) {
     };
     window.addEventListener("focus", refreshOnFocus);
     document.addEventListener("visibilitychange", refreshOnFocus);
+    const atproto = createAtprotoApi(host, getToken, () => store.getSnapshot().user?.id ?? null);
+    let resolverUserId = store.getSnapshot().user?.id ?? null;
+    store.subscribe((state) => {
+        const userId = state.user?.id ?? null;
+        if (userId !== resolverUserId)
+            atproto.invalidate();
+        resolverUserId = userId;
+    });
     const flow = {
         get user() {
             return store.getSnapshot().user;
@@ -541,6 +550,7 @@ export function createFlow(options = {}) {
         getToken,
         mintAudience,
         rooms: createRoomsApi(host, getToken),
+        atproto,
         signMessage: async (args) => {
             const mod = await import("./signing");
             return mod.signMessage(buildSigningContext(), args);

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

@@ -1,16 +1,21 @@
 export { defaultIdHost, isLocalHostname } from "../id-host";
-export type { AccessKeyOptions, ActionCatalogEntry, ActionCatalogResponse, ActionCurve, ActionEventRequest, ActionEventResponse, ActionSubjectRef, ActionSurface, ActionsApi, ActionTransitionKind, ActiveAction, ActiveActionResponse, ActiveSessionConflict, AdditionalSession, Address, BrowserAccount, BrowserAccounts, CatalogFieldRef, ClockAnchor, ConnectCapabilities, ConnectResponse, CreateFlowOptions, CreateStudySubjectInput, CurrentAction, DialogHost, FinishActionRequest, FinishActionResponse, FinishedSummary, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, FocusApi, FocusPhase, FocusSessionEvent, FocusSessionState, ListStudySessionsOptions, ListStudySubjectsOptions, LoginOptions, MarkNotificationsReadInput, MethodName, MountFlowWidgetOptions, MountProfileOptions, NotificationCounts, NotificationEntry, NotificationPage, NotificationReadResult, NotificationRefusal, OpenProfileOptions, ProfileButtonHandle, ProfilePosition, RoomMemberEntry, Session, StartActionInput, StartActionResponse, StartActionResult, StartFocusRequest, StudyApi, StudyCatalog, StudyCategory, StudyCategoryTotals, StudyField, StudyRange, StudySearchHit, StudySessionEntry, StudySessionPage, StudySubject, StudySubjectList, StudySubjectRefusal, StudySubjectRemovalResponse, StudySubjectResponse, StudySubjectTotals, StudySummary, SwitchAccountOptions, UpdateStudySubjectInput, UserActionSurface, XpEstimateContext, XpMode, } from "../types";
+export type { AccessKeyOptions, ActionCatalogEntry, ActionCatalogResponse, ActionCurve, ActionEventRequest, ActionEventResponse, ActionSubjectRef, ActionSurface, ActionsApi, ActionTransitionKind, ActiveAction, ActiveActionResponse, ActiveSessionConflict, AdditionalSession, Address, AtprotoApi, AtprotoResolution, AtprotoResolutionFailure, AtprotoResolveOptions, BrowserAccount, BrowserAccounts, CatalogFieldRef, ClockAnchor, ConnectCapabilities, ConnectResponse, CreateFlowOptions, CreateStudySubjectInput, CurrentAction, DialogHost, FinishActionRequest, FinishActionResponse, FinishedSummary, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, FocusApi, FocusPhase, FocusSessionEvent, FocusSessionState, ListStudySessionsOptions, ListStudySubjectsOptions, LoginOptions, MarkNotificationsReadInput, MethodName, MountFlowWidgetOptions, MountProfileOptions, NotificationCounts, NotificationEntry, NotificationPage, NotificationReadResult, NotificationRefusal, OpenProfileOptions, PasskeyPrfOptions, ProfileButtonHandle, ProfilePosition, RoomMemberEntry, Session, StartActionInput, StartActionResponse, StartActionResult, StartFocusRequest, StudyApi, StudyCatalog, StudyCategory, StudyCategoryTotals, StudyField, StudyRange, StudySearchHit, StudySessionEntry, StudySessionPage, StudySubject, StudySubjectList, StudySubjectRefusal, StudySubjectRemovalResponse, StudySubjectResponse, StudySubjectTotals, StudySummary, SwitchAccountOptions, UpdateStudySubjectInput, UserActionSurface, XpEstimateContext, XpMode, } from "../types";
+export type { NoteBlob, NoteCollection, NoteOperation, NoteRecord, NoteResponses, NoteStoredRecord, NoteVaultHeader, } from "../types/note-transport";
 export { consistencyCurve, estimateActionXp, FLOW_SCORE_MAX, flowMultiplier, } from "../xp/curve";
 export { ActionsRequestError, createActionsApi, isActiveSessionConflict, } from "./actions";
+export { AtprotoRequestError, createAtprotoApi } from "./atproto-resolver";
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { createFlowWidget } from "./flow-widget";
 export { actionHeadline, anchorFor, catalogFieldIndex, createFocusApi, elapsedSeconds, fieldsCoveredBySubjects, focusSessionReducer, formatElapsed, hitLabel, INITIAL_FOCUS_STATE, MEDITATION_SOURCE, matchScore, normalizeSearchText, REANCHOR_TOLERANCE_SECONDS, recentSubjects, STUDY_SOURCE, searchStudy, shouldReanchor, } from "./focus";
 export { METHODS } from "./methods";
+export { createNoteTransport, NoteTransportError } from "./note-transport";
 export { closeProfile, openProfile } from "./open-profile";
+export { evaluatePasskeyPrf, PasskeyPrfError } from "./passkey-prf";
 export { createProfileButton } from "./profile-button";
 export type { ReportOperation, ReportRequest, ReportResponse } from "./reports";
 export { createReportsApi, ReportRequestError } from "./reports";
 export { createRoomsApi, RoomsRequestError } from "./rooms";
+export { getConnectedPasskey } from "./session";
 export { createStaticFlow } from "./static-flow";
 export { createStudyApi, StudyRequestError } from "./study";

package/dist/sdk/client/index.js

@@ -1,14 +1,18 @@
 export { defaultIdHost, isLocalHostname } from "../id-host";
 export { consistencyCurve, estimateActionXp, FLOW_SCORE_MAX, flowMultiplier, } from "../xp/curve";
 export { ActionsRequestError, createActionsApi, isActiveSessionConflict, } from "./actions";
+export { AtprotoRequestError, createAtprotoApi } from "./atproto-resolver";
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { createFlowWidget } from "./flow-widget";
 export { actionHeadline, anchorFor, catalogFieldIndex, createFocusApi, elapsedSeconds, fieldsCoveredBySubjects, focusSessionReducer, formatElapsed, hitLabel, INITIAL_FOCUS_STATE, MEDITATION_SOURCE, matchScore, normalizeSearchText, REANCHOR_TOLERANCE_SECONDS, recentSubjects, STUDY_SOURCE, searchStudy, shouldReanchor, } from "./focus";
 export { METHODS } from "./methods";
+export { createNoteTransport, NoteTransportError } from "./note-transport";
 export { closeProfile, openProfile } from "./open-profile";
+export { evaluatePasskeyPrf, PasskeyPrfError } from "./passkey-prf";
 export { createProfileButton } from "./profile-button";
 export { createReportsApi, ReportRequestError } from "./reports";
 export { createRoomsApi, RoomsRequestError } from "./rooms";
+export { getConnectedPasskey } from "./session";
 export { createStaticFlow } from "./static-flow";
 export { createStudyApi, StudyRequestError } from "./study";

package/dist/sdk/client/note-transport.d.ts

@@ -0,0 +1,15 @@
+import type { AtprotoApi, AtprotoResolution } from "../types/atproto";
+import type { NoteBlob, NoteOperation, NoteResponses } from "../types/note-transport";
+export declare class NoteTransportError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, status: number);
+}
+/** Ciphertext-only Auth transport; the browser never receives provider tokens or DPoP keys. */
+export declare function createNoteTransport(host: string, getToken: () => Promise<string | null>, getUserId: () => string | null, getSessionVersion: () => number, resolver: AtprotoApi, expectedIdentity: Pick<AtprotoResolution, "did" | "identityVersion">): {
+    records<T extends NoteOperation>(operation: T, signal?: AbortSignal): Promise<NoteResponses[T["method"]]>;
+    download(cid: string, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer>>;
+    upload(bytes: Uint8Array<ArrayBuffer>, signal?: AbortSignal): Promise<{
+        blob: NoteBlob;
+    }>;
+};

package/dist/sdk/client/note-transport.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+export class NoteTransportError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(code);
+        this.code = code;
+        this.status = status;
+        this.name = "NoteTransportError";
+    }
+}
+/** Ciphertext-only Auth transport; the browser never receives provider tokens or DPoP keys. */
+export function createNoteTransport(host, getToken, getUserId, getSessionVersion, resolver, expectedIdentity) {
+    const pinnedIdentity = { ...expectedIdentity };
+    async function request(action, body, signal) {
+        signal?.throwIfAborted();
+        const userId = getUserId();
+        const version = getSessionVersion();
+        if (!userId)
+            throw new NoteTransportError("SIGN_IN_REQUIRED", 401);
+        const unchanged = () => {
+            if (getUserId() !== userId || getSessionVersion() !== version)
+                throw new NoteTransportError("ACCOUNT_CHANGED", 409);
+        };
+        const resolution = await resolver.resolve({ freshness: "refresh", signal });
+        unchanged();
+        if (resolution.did !== pinnedIdentity.did ||
+            resolution.identityVersion !== pinnedIdentity.identityVersion) {
+            resolver.invalidate();
+            throw new NoteTransportError("ACCOUNT_CHANGED", 409);
+        }
+        if (resolution.lifecycle !== "active" ||
+            resolution.authorization !== "connected")
+            throw new NoteTransportError("RECONNECT_REQUIRED", 403);
+        const token = await getToken();
+        unchanged();
+        if (!token)
+            throw new NoteTransportError("SIGN_IN_REQUIRED", 401);
+        let response;
+        try {
+            response = await fetch(`${host}/api/atproto/note/${action}`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "X-Flow-User-Id": userId,
+                    "X-Flow-At-Did": pinnedIdentity.did,
+                    "X-Flow-Identity-Version": pinnedIdentity.identityVersion,
+                    "Content-Type": action === "upload"
+                        ? "application/octet-stream"
+                        : "application/json",
+                },
+                body,
+                signal,
+            });
+        }
+        catch {
+            signal?.throwIfAborted();
+            unchanged();
+            throw new NoteTransportError("PDS_UNAVAILABLE", 503);
+        }
+        const data = action === "download" && response.ok
+            ? new Uint8Array(await response.arrayBuffer())
+            : await response.json().catch(() => null);
+        signal?.throwIfAborted();
+        unchanged();
+        if (!response.ok) {
+            const parsed = z.object({ code: z.string() }).safeParse(data);
+            const code = parsed.success ? parsed.data.code : "PDS_UNAVAILABLE";
+            if (code === "ACCOUNT_CHANGED" || code === "RECONNECT_REQUIRED")
+                resolver.invalidate();
+            throw new NoteTransportError(code, response.status);
+        }
+        const after = await resolver.resolve({ freshness: "refresh", signal });
+        unchanged();
+        if (after.did !== pinnedIdentity.did ||
+            after.identityVersion !== pinnedIdentity.identityVersion) {
+            resolver.invalidate();
+            throw new NoteTransportError("ACCOUNT_CHANGED", 409);
+        }
+        if (data instanceof Uint8Array)
+            return new Uint8Array(data);
+        const parsed = z.record(z.string(), z.unknown()).safeParse(data);
+        if (!parsed.success)
+            throw new NoteTransportError("INVALID_RESPONSE", 502);
+        // SAFETY: Auth validates method-specific ciphertext schemas and strips provider secrets; the SDK preserves those named contracts.
+        return parsed.data;
+    }
+    return {
+        async records(operation, signal) {
+            // SAFETY: Auth validates the selected operation's named response schema.
+            return (await request("records", JSON.stringify(operation), signal));
+        },
+        async download(cid, signal) {
+            const result = await request("download", JSON.stringify({ cid }), signal);
+            if (!(result instanceof Uint8Array))
+                throw new NoteTransportError("INVALID_RESPONSE", 502);
+            return result;
+        },
+        async upload(bytes, signal) {
+            // SAFETY: Auth validates the upload response as a single standard octet-stream blob reference.
+            return (await request("upload", bytes, signal));
+        },
+    };
+}

package/dist/sdk/client/passkey-prf.d.ts

@@ -0,0 +1,8 @@
+import type { FlowCredential } from "../types/auth";
+import type { PasskeyPrfOptions } from "../types/sdk";
+export declare class PasskeyPrfError extends Error {
+    readonly code: "PASSKEY_REQUIRED" | "PRF_UNAVAILABLE" | "ACCOUNT_CHANGED" | "INVALID_INPUT";
+    constructor(code: "PASSKEY_REQUIRED" | "PRF_UNAVAILABLE" | "ACCOUNT_CHANGED" | "INVALID_INPUT");
+}
+/** Evaluate only the connected passkey. Output is client-only key material: never serialize or log it. */
+export declare function evaluatePasskeyPrf(getCredential: () => FlowCredential | null, getUserId: () => string | null, getSessionVersion: () => number, options: PasskeyPrfOptions): Promise<Uint8Array<ArrayBuffer>>;

package/dist/sdk/client/passkey-prf.js

@@ -0,0 +1,67 @@
+export class PasskeyPrfError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "PasskeyPrfError";
+    }
+}
+/** Evaluate only the connected passkey. Output is client-only key material: never serialize or log it. */
+export async function evaluatePasskeyPrf(getCredential, getUserId, getSessionVersion, options) {
+    options.signal?.throwIfAborted();
+    const credential = getCredential();
+    const userId = getUserId();
+    const sessionVersion = getSessionVersion();
+    if (!credential || !userId)
+        throw new PasskeyPrfError("PASSKEY_REQUIRED");
+    if (options.input.byteLength !== 32 || !options.rpId)
+        throw new PasskeyPrfError("INVALID_INPUT");
+    let id;
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(credential.id))
+            throw new Error();
+        id = Uint8Array.from(atob(credential.id.replace(/-/g, "+").replace(/_/g, "/")), (character) => character.charCodeAt(0));
+    }
+    catch {
+        throw new PasskeyPrfError("INVALID_INPUT");
+    }
+    const unchanged = () => {
+        if (getSessionVersion() !== sessionVersion ||
+            getUserId() !== userId ||
+            getCredential()?.id !== credential.id)
+            throw new PasskeyPrfError("ACCOUNT_CHANGED");
+    };
+    if (!globalThis.navigator?.credentials || !globalThis.PublicKeyCredential)
+        throw new PasskeyPrfError("PRF_UNAVAILABLE");
+    let assertion;
+    try {
+        assertion = await navigator.credentials.get({
+            publicKey: {
+                challenge: crypto.getRandomValues(new Uint8Array(32)),
+                rpId: options.rpId,
+                allowCredentials: [{ type: "public-key", id }],
+                userVerification: "required",
+                timeout: 60_000,
+                extensions: { prf: { eval: { first: options.input.slice().buffer } } },
+            },
+            signal: options.signal,
+        });
+    }
+    catch {
+        options.signal?.throwIfAborted();
+        unchanged();
+        throw new PasskeyPrfError("PRF_UNAVAILABLE");
+    }
+    options.signal?.throwIfAborted();
+    unchanged();
+    if (!(assertion instanceof PublicKeyCredential))
+        throw new PasskeyPrfError("PRF_UNAVAILABLE");
+    const actualId = new Uint8Array(assertion.rawId);
+    if (actualId.length !== id.length ||
+        actualId.some((byte, i) => byte !== id[i]))
+        throw new PasskeyPrfError("PRF_UNAVAILABLE");
+    const result = assertion.getClientExtensionResults().prf?.results?.first;
+    if (!(result instanceof ArrayBuffer) || result.byteLength !== 32)
+        throw new PasskeyPrfError("PRF_UNAVAILABLE");
+    return new Uint8Array(result.slice(0));
+}