@arcblock/did-connect-service 4.0.0-beta.8

package/dist/handlers/passkey-handler.js

@@ -0,0 +1,1020 @@
+/**
+ * Auth — Core auth handler for Cloudflare Workers.
+ *
+ * Routes (prefix-stripped, under /.well-known/service/api/passkey):
+ *   GET  /register  — Generate registration challenge options
+ *   POST /register  — Verify registration credential, create user, issue JWT
+ *   GET  /auth      — Generate authentication challenge options
+ *   POST /auth      — Verify authentication credential, issue JWT
+ *
+ * Session and logout are handled by auth-handler at /did/session and /did/logout.
+ */
+import { deriveAccessKeyId, isAccessKeyToken } from "../access/access-key-util.js";
+import { checkLoginAccess } from "../access/login-access-check.js";
+import { LOGIN_PROVIDER } from "../constants.js";
+import { ensureInstanceMembership } from "../identity/auto-membership.js";
+import { signJWT, verifyJWT } from "../identity/jwt.js";
+import { derivePasskeyDID } from "../identity/passkey-did.js";
+import { generateChallengeOptions, verifyAuthentication, verifyRegistration } from "../identity/webauthn.js";
+import { detectLocale } from "../locale.js";
+import { renderLoginPage } from "../pages/login-page.js";
+const DEFAULT_COOKIE_NAME = "login_token";
+const DEFAULT_EXPIRES_IN = 7 * 24 * 60 * 60; // 7 days
+const MAX_NAME_LENGTH = 64;
+/** Sanitize and validate user-provided name. */
+function sanitizeName(raw) {
+    if (!raw)
+        return undefined;
+    // Strip control chars (C0 range + DEL), trim, limit length
+    let clean = "";
+    for (const ch of raw) {
+        const code = ch.charCodeAt(0);
+        if (code >= 0x20 && code !== 0x7f)
+            clean += ch;
+    }
+    clean = clean.trim().slice(0, MAX_NAME_LENGTH);
+    return clean || undefined;
+}
+function jsonResponse(data, status = 200, headers) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: {
+            "Content-Type": "application/json",
+            "Cache-Control": "private, no-store",
+            ...headers,
+        },
+    });
+}
+function errorResponse(message, status = 400) {
+    return jsonResponse({ error: message }, status);
+}
+/**
+ * Extract Bearer token from Authorization header and resolve access key caller.
+ * Returns null if no access key token or if validation fails.
+ */
+export async function resolveAccessKeyCaller(request, store, instanceDid) {
+    const authHeader = request.headers.get("Authorization");
+    if (!authHeader)
+        return null;
+    const token = authHeader.replace(/^Bearer\s+/i, "").trim();
+    if (!isAccessKeyToken(token))
+        return null;
+    const accessKeyId = deriveAccessKeyId(token);
+    if (!accessKeyId)
+        return null;
+    const key = await store.getAccessKeyById(accessKeyId);
+    if (!key)
+        return null;
+    // Check expiration
+    if (key.expireAt && new Date(key.expireAt) < new Date())
+        return null;
+    // Instance ownership check: instance-scoped key must match request's instanceDid
+    if (key.instanceDid) {
+        // Key is scoped to a specific instance — must match
+        if (!instanceDid || key.instanceDid !== instanceDid) {
+            return null; // key belongs to a different instance or no instance context
+        }
+    }
+    // Check creator exists and is not blocked
+    const creator = await store.getUserByDid(key.createdBy);
+    if (!creator)
+        return null;
+    // Fire-and-forget: update lastUsedAt
+    store.refreshAccessKeyLastUsed(accessKeyId).catch(() => { });
+    return {
+        did: creator.did,
+        pk: creator.pk,
+        role: key.role,
+        displayName: creator.fullName ?? undefined,
+        blocked: !creator.approved,
+        accessKeyId,
+    };
+}
+export class Auth {
+    store;
+    jwtSecret;
+    rpName;
+    rpID;
+    jwtExpiresIn;
+    cookieName;
+    constructor(options) {
+        this.store = options.store;
+        this.jwtSecret = options.jwtSecret;
+        this.rpName = options.rpName;
+        this.rpID = options.rpID;
+        this.jwtExpiresIn = options.jwtExpiresIn ?? DEFAULT_EXPIRES_IN;
+        this.cookieName = options.cookieName ?? DEFAULT_COOKIE_NAME;
+    }
+    /** Expose the store for sharing with TeamHandler. */
+    getStore() {
+        return this.store;
+    }
+    /**
+     * Handle auth API requests. Expects the prefix to be already stripped —
+     * internally matches /register (GET/POST) and /auth (GET/POST).
+     */
+    async fetch(request, instanceDid) {
+        const url = new URL(request.url);
+        // Strip the well-known prefix to get internal route
+        const path = url.pathname.replace("/.well-known/service/api/passkey", "");
+        if (path === "/register" && request.method === "GET") {
+            return this.handleRegisterRequest(request, instanceDid);
+        }
+        if (path === "/register" && request.method === "POST") {
+            return this.handleRegisterResponse(request, instanceDid);
+        }
+        if (path === "/auth" && request.method === "GET") {
+            return this.handleAuthRequest(request);
+        }
+        if (path === "/auth" && request.method === "POST") {
+            return this.handleAuthResponse(request, instanceDid);
+        }
+        if (path === "/connect/register" && request.method === "POST") {
+            return this.handleConnectRegister(request);
+        }
+        if (path === "/connect/verify" && request.method === "POST") {
+            return this.handleConnectVerify(request, instanceDid);
+        }
+        if (path === "/disconnect" && request.method === "POST") {
+            return this.handlePasskeyDisconnect(request, instanceDid);
+        }
+        if (path === "/rename" && request.method === "POST") {
+            return this.handlePasskeyRename(request, instanceDid);
+        }
+        return errorResponse("Not found", 404);
+    }
+    /** Verify JWT from cookie — hot path, pure crypto, no D1. */
+    async verify(request) {
+        const cookie = request.headers.get("Cookie");
+        if (!cookie)
+            return null;
+        const token = this.extractCookie(cookie);
+        if (!token)
+            return null;
+        const payload = await verifyJWT(token, this.jwtSecret);
+        if (!payload?.did)
+            return null;
+        return {
+            did: payload.did,
+            pk: payload.pk ?? "",
+            displayName: (payload.fullName ?? payload.displayName),
+        };
+    }
+    /**
+     * Full verification: access key (Bearer) first, then JWT + DB check.
+     * Returns null if neither auth method succeeds, or if user is blocked/deleted.
+     */
+    async verifyFull(request, instanceDid) {
+        // Try access key auth first (pass instanceDid for isolation check)
+        const akCaller = await this.verifyAccessKey(request, instanceDid);
+        if (akCaller)
+            return akCaller;
+        // Fall back to JWT auth
+        const caller = await this.verify(request);
+        if (!caller)
+            return null;
+        const user = await this.store.getUserByDid(caller.did);
+        if (!user?.approved)
+            return null;
+        // Prefer instance membership role over global users.role
+        let role = user.role ?? "guest";
+        if (instanceDid) {
+            const membership = await this.store.getMembership(caller.did, instanceDid);
+            if (membership?.role) {
+                role = membership.role;
+            }
+            else if (role !== "owner" && role !== "admin") {
+                // No membership + not system owner/admin → guest (consistent with RPC resolveIdentity)
+                role = "guest";
+            }
+            // System owner/admin punch-through: keep global role for platform management
+        }
+        return {
+            ...caller,
+            displayName: user.fullName ?? caller.displayName,
+            role,
+            avatar: `/.well-known/service/avatar/${caller.did}`,
+        };
+    }
+    /**
+     * Verify access key from Authorization: Bearer header.
+     * Returns CallerIdentity with the key's role, or null.
+     */
+    async verifyAccessKey(request, instanceDid) {
+        const resolved = await resolveAccessKeyCaller(request, this.store, instanceDid);
+        if (!resolved || resolved.blocked)
+            return null;
+        return {
+            did: resolved.did,
+            pk: resolved.pk,
+            displayName: resolved.displayName,
+            role: resolved.role,
+        };
+    }
+    /** Return the login page HTML, filtering methods by builtin-providers settings. */
+    async getLoginPage(instanceDid, overrides, request) {
+        // Read builtin-providers config to filter methods
+        let methods = overrides?.methods;
+        if (instanceDid) {
+            try {
+                const raw = await this.store.getSetting(instanceDid, "auth:builtin-providers");
+                if (raw) {
+                    const config = JSON.parse(raw);
+                    // Build methods based on what's enabled, keeping existing order
+                    const methodMap = { passkey: "passkey", "did-connect": "wallet", email: "email" };
+                    if (methods) {
+                        methods = methods.filter((m) => {
+                            const configKey = methodMap[m];
+                            if (!configKey)
+                                return true; // oauth and unknown methods pass through
+                            const entry = config[configKey];
+                            return !entry || entry.enabled !== false;
+                        });
+                    }
+                }
+            }
+            catch {
+                // On error, keep all methods enabled (safe degradation)
+            }
+        }
+        // Federation: check if branding should come from Master
+        let brandingSourceDid = instanceDid;
+        if (instanceDid) {
+            const fedRole = await this.store.getSetting(instanceDid, "federation:role");
+            const fedEnabled = await this.store.getSetting(instanceDid, "federation:enabled");
+            const fedGroupId = await this.store.getSetting(instanceDid, "federation:groupId");
+            if (fedRole === "member" && fedEnabled === "true" && fedGroupId) {
+                brandingSourceDid = fedGroupId; // Master's instanceDid
+            }
+        }
+        // Read branding: appName from local instance, logo + theme from Master in federation
+        const isFederated = brandingSourceDid !== instanceDid;
+        let appName = this.rpName;
+        let masterAppName;
+        let appLogo;
+        let themePrefer;
+        // appName always from local instance (not Master) — users should see the sub-site's name
+        if (instanceDid) {
+            try {
+                const localBrandingRaw = await this.store.getSetting(instanceDid, "app:branding");
+                if (localBrandingRaw) {
+                    const localBranding = JSON.parse(localBrandingRaw);
+                    if (localBranding.name)
+                        appName = localBranding.name;
+                }
+            }
+            catch { /* keep rpName default */ }
+        }
+        // Logo + theme from brandingSourceDid (Master in federation); also read Master's name for hint
+        if (brandingSourceDid) {
+            try {
+                const [brandingRaw, logosRaw, themeRaw] = await Promise.all([
+                    isFederated ? this.store.getSetting(brandingSourceDid, "app:branding") : Promise.resolve(null),
+                    this.store.getSetting(brandingSourceDid, "app:logos"),
+                    this.store.getSetting(brandingSourceDid, "app:theme"),
+                ]);
+                if (isFederated && brandingRaw) {
+                    const masterBranding = JSON.parse(brandingRaw);
+                    if (masterBranding.name)
+                        masterAppName = masterBranding.name;
+                }
+                if (logosRaw) {
+                    const logos = JSON.parse(logosRaw);
+                    if (logos.square) {
+                        appLogo = overrides?.masterOAuthOrigin
+                            ? `${overrides.masterOAuthOrigin}/.well-known/service/blocklet/logo?t=${Date.now()}`
+                            : `/.well-known/service/blocklet/logo?t=${Date.now()}`;
+                    }
+                }
+                if (themeRaw) {
+                    const theme = JSON.parse(themeRaw);
+                    const concept = theme.concepts?.find((c) => c.id === theme.currentConceptId);
+                    const prefer = concept?.prefer || theme.prefer;
+                    if (prefer === "light" || prefer === "dark")
+                        themePrefer = prefer;
+                    else if (prefer === "system")
+                        themePrefer = "auto";
+                }
+            }
+            catch {
+                // On error, use defaults
+            }
+        }
+        // Detect locale from request
+        const locale = request ? detectLocale(request) : "en";
+        const html = renderLoginPage({
+            apiPrefix: "/.well-known/service/api/did",
+            appName,
+            appLogo,
+            methods,
+            oauthProviders: overrides?.oauthProviders,
+            locale,
+            theme: themePrefer,
+            masterOAuthOrigin: overrides?.masterOAuthOrigin,
+            masterAppName,
+        });
+        return new Response(html, {
+            headers: {
+                "Content-Type": "text/html; charset=utf-8",
+                "Cache-Control": "private, no-store",
+            },
+        });
+    }
+    // ─── Internal route handlers ────────────────────────────────────────
+    /** GET /register — Generate registration challenge options.
+     *  Always returns options (even when registration is gated) because:
+     *  - Re-registration of existing passkeys bypasses the gate
+     *  - The registrationAllowed flag lets the client show/hide UI
+     *  - The actual gate is enforced at POST /register time */
+    async handleRegisterRequest(request, instanceDid) {
+        const rpID = this.getRPID(request);
+        const challengeId = crypto.randomUUID();
+        const challenge = crypto.randomUUID();
+        const url = new URL(request.url);
+        const userName = sanitizeName(url.searchParams.get("name") ?? undefined);
+        const invitationId = url.searchParams.get("invitationId") ?? undefined;
+        const eligibility = await this.checkRegistrationEligibility(invitationId, instanceDid);
+        // Audit blocked registration attempts at GET time (frontend won't POST)
+        if (!eligibility.allowed) {
+            const ip = request.headers.get("CF-Connecting-IP") ?? undefined;
+            const hostname = new URL(request.url).hostname;
+            this.store.createAuditLog({
+                action: "user.register_blocked",
+                operatorDid: "anonymous",
+                metadata: {
+                    source: "passkey",
+                    method: eligibility.method,
+                    reason: eligibility.reason,
+                    invitationId: invitationId ?? null,
+                    domain: hostname,
+                },
+                ip,
+                instanceDid,
+            }).catch(() => { });
+        }
+        await this.store.saveChallenge(challengeId, challenge, invitationId);
+        this.store.purgeExpiredChallenges().catch(() => { });
+        const options = await generateChallengeOptions({
+            rpID,
+            rpName: this.rpName,
+            challenge,
+            userName,
+        });
+        // Return flattened WebAuthn options — Connect SDK passes entire response
+        // as optionsJSON to startRegistration({ optionsJSON }), reads .challenge directly.
+        // challengeId kept for our admin UI compatibility.
+        return jsonResponse({
+            ...options.registration,
+            challengeId,
+            registrationAllowed: eligibility.allowed,
+        });
+    }
+    /** POST /register — Verify registration credential, create user, issue JWT.
+     *  Two calling conventions:
+     *  1. Admin UI: body = { challengeId, credential, name? }
+     *  2. Connect SDK: body = WebAuthn credential directly, query ?challenge=<base64> */
+    async handleRegisterResponse(request, instanceDid) {
+        const url = new URL(request.url);
+        const body = (await request.json());
+        // Connect SDK sends credential as entire body, challenge in query param
+        const credential = body.credential || (body.id ? body : undefined);
+        if (!credential) {
+            return errorResponse("Missing required fields");
+        }
+        const userName = sanitizeName(body.name ?? undefined);
+        // Resolve challenge: try challengeId (admin UI) → query param challenge (SDK)
+        const stored = await this.resolveChallenge(body.challengeId, url.searchParams.get("challenge"));
+        if (!stored) {
+            return errorResponse("Invalid or expired challenge");
+        }
+        await this.store.deleteChallenge(stored.id);
+        const { challenge, invitationId } = stored;
+        const rpID = this.getRPID(request);
+        const requestUrl = new URL(request.url);
+        const origin = request.headers.get("Origin") || requestUrl.origin;
+        const ip = request.headers.get("CF-Connecting-IP") ?? undefined;
+        const hostname = requestUrl.hostname;
+        const cookieDomain = this.rpID ? rpID : undefined;
+        const ctx = {
+            expectedChallenge: challenge,
+            expectedOrigin: origin,
+            expectedRPID: rpID,
+            ip,
+            hostname,
+            cookieDomain,
+            request,
+        };
+        try {
+            return await this.handleRegistrationVerify(credential, ctx, userName, invitationId ?? undefined, instanceDid);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Registration verification failed";
+            return errorResponse(message);
+        }
+    }
+    /** GET /auth — Generate authentication challenge options. */
+    async handleAuthRequest(request) {
+        const rpID = this.getRPID(request);
+        const challengeId = crypto.randomUUID();
+        const challenge = crypto.randomUUID();
+        await this.store.saveChallenge(challengeId, challenge);
+        this.store.purgeExpiredChallenges().catch(() => { });
+        const options = await generateChallengeOptions({
+            rpID,
+            rpName: this.rpName,
+            challenge,
+        });
+        // Return flattened WebAuthn options — Connect SDK passes entire response
+        // as optionsJSON to startAuthentication({ optionsJSON }), reads .challenge directly.
+        return jsonResponse({
+            ...options.authentication,
+            challengeId,
+        });
+    }
+    /** POST /auth — Verify authentication credential, issue JWT.
+     *  Two calling conventions:
+     *  1. Admin UI: body = { challengeId, credential }
+     *  2. Connect SDK: body = WebAuthn credential directly, query ?challenge=<base64> */
+    async handleAuthResponse(request, instanceDid) {
+        const url = new URL(request.url);
+        const body = (await request.json());
+        const credential = body.credential || (body.id ? body : undefined);
+        if (!credential) {
+            return errorResponse("Missing required fields");
+        }
+        const stored = await this.resolveChallenge(body.challengeId, url.searchParams.get("challenge"));
+        if (!stored) {
+            return errorResponse("Invalid or expired challenge");
+        }
+        await this.store.deleteChallenge(stored.id);
+        const { challenge } = stored;
+        const rpID = this.getRPID(request);
+        const requestUrl = new URL(request.url);
+        const origin = request.headers.get("Origin") || requestUrl.origin;
+        const ip = request.headers.get("CF-Connecting-IP") ?? undefined;
+        const hostname = requestUrl.hostname;
+        const cookieDomain = this.rpID ? rpID : undefined;
+        const ctx = {
+            expectedChallenge: challenge,
+            expectedOrigin: origin,
+            expectedRPID: rpID,
+            ip,
+            hostname,
+            cookieDomain,
+            request,
+        };
+        try {
+            return await this.handleAuthenticationVerify(credential, ctx, instanceDid);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Authentication verification failed";
+            return errorResponse(message);
+        }
+    }
+    async handleRegistrationVerify(credential, ctx, userName, invitationId, instanceDid) {
+        const { expectedChallenge, expectedOrigin, expectedRPID, ip, hostname, cookieDomain, request } = ctx;
+        const verification = await verifyRegistration({
+            response: credential,
+            expectedChallenge,
+            expectedOrigin,
+            expectedRPID,
+        });
+        if (!verification.verified || !verification.registrationInfo) {
+            return errorResponse("Registration verification failed");
+        }
+        const { credential: regCredential, credentialDeviceType, credentialBackedUp, } = verification.registrationInfo;
+        const publicKeyBytes = regCredential.publicKey;
+        const credentialId = regCredential.id;
+        // Derive DID from passkey public key
+        const passkeyDid = derivePasskeyDID(publicKeyBytes);
+        const pkBase64 = uint8ArrayToBase64(publicKeyBytes);
+        // Check if this passkey already exists (re-registration)
+        const existing = await this.store.getConnectedAccountByDid(passkeyDid);
+        if (existing) {
+            // Treat as login for existing passkey
+            await this.store.updateLastLogin(existing.userDid, ip, hostname);
+            await ensureInstanceMembership(this.store, existing.userDid, instanceDid);
+            const user = await this.store.getUserByDid(existing.userDid);
+            // Audit log: re-registration login
+            await this.store.createAuditLog({
+                action: "user.login",
+                operatorDid: existing.userDid,
+                metadata: { source: "passkey", type: "re-registration", domain: hostname },
+                ip,
+                instanceDid,
+            });
+            return this.issueJWT(existing.userDid, existing.pk ?? pkBase64, user?.fullName ?? undefined, user?.role ?? undefined, cookieDomain, request, "passkey", instanceDid);
+        }
+        // Server-side registration gate (L2 defense)
+        const eligibility = await this.checkRegistrationEligibility(invitationId, instanceDid);
+        if (!eligibility.allowed) {
+            await this.store.createAuditLog({
+                action: "user.register_blocked",
+                operatorDid: passkeyDid,
+                metadata: {
+                    source: "passkey",
+                    method: eligibility.method,
+                    reason: eligibility.reason,
+                    invitationId: invitationId ?? null,
+                    domain: hostname,
+                },
+                ip,
+                instanceDid,
+            });
+            return errorResponse("Registration is not allowed. An invitation is required.", 403);
+        }
+        // New registration: user DID = first passkey DID
+        const userDid = passkeyDid;
+        await this.store.createUser({
+            did: userDid,
+            pk: pkBase64,
+            fullName: userName,
+            sourceProvider: LOGIN_PROVIDER.PASSKEY,
+            ip,
+            domain: hostname,
+        });
+        const transports = credential?.response
+            ?.transports;
+        await this.store.createConnectedAccount({
+            did: passkeyDid,
+            pk: pkBase64,
+            userDid,
+            provider: "passkey",
+            id: credentialId,
+            extra: JSON.stringify({
+                transports,
+                rpID: expectedRPID,
+                credentialDeviceType,
+                credentialBackedUp,
+            }),
+            userInfo: JSON.stringify({ name: userName || "Passkey User" }),
+            ip,
+        });
+        await this.store.incrementPasskeyCount(userDid);
+        // Resolve the role for this new registration
+        // Priority: first-user → invitation role → instance-first-owner → "member"
+        const userCount = await this.store.getUserCount();
+        let role;
+        // Resolve invitation role (do NOT consume here — the invite page's
+        // POST /accept endpoint handles consumption atomically)
+        let invitedRole;
+        if (invitationId) {
+            const invitation = await this.store.getInvitation(invitationId);
+            if (invitation && invitation.status === "active" && invitation.useCount < invitation.maxUses) {
+                invitedRole = invitation.role;
+            }
+        }
+        if (userCount === 1) {
+            // First-user-is-owner: global first user gets global owner role
+            await this.store.updateUserRole(userDid, "owner");
+            role = "owner";
+        }
+        if (instanceDid) {
+            const members = await this.store.listMemberships(instanceDid);
+            const hasOwner = members.some((m) => m.role === "owner");
+            // Instance role: first-owner > invitation role > "guest"
+            const instanceRole = hasOwner ? (invitedRole ?? role ?? "guest") : "owner";
+            const existing = await this.store.getMembership(userDid, instanceDid);
+            if (!existing) {
+                await this.store.createMembership(userDid, instanceDid, instanceRole);
+            }
+            if (!role)
+                role = instanceRole;
+        }
+        else if (invitedRole && !role) {
+            // System-level invitation: set global user role
+            await this.store.updateUserRole(userDid, invitedRole);
+            role = invitedRole;
+        }
+        // Audit log: new registration
+        await this.store.createAuditLog({
+            action: "user.register",
+            operatorDid: userDid,
+            metadata: { role: role ?? "guest", source: "passkey", domain: hostname },
+            ip,
+            instanceDid,
+        });
+        return this.issueJWT(userDid, pkBase64, userName, role, cookieDomain, request, "passkey", instanceDid);
+    }
+    async handleAuthenticationVerify(credential, ctx, instanceDid) {
+        const { expectedChallenge, expectedOrigin, expectedRPID, ip, hostname, cookieDomain, request } = ctx;
+        const credentialData = credential;
+        const credentialId = credentialData.id;
+        // Look up stored passkey by credential ID
+        const stored = await this.store.getConnectedAccountById(credentialId);
+        if (!stored?.extra) {
+            return errorResponse("Unknown credential");
+        }
+        const extra = JSON.parse(stored.extra);
+        // Reconstruct public key from base64
+        const publicKey = base64ToUint8Array(stored.pk ?? "");
+        const verification = await verifyAuthentication({
+            response: credential,
+            expectedChallenge,
+            expectedOrigin,
+            expectedRPID,
+            credential: {
+                id: credentialId,
+                publicKey,
+                counter: stored.counter,
+                transports: extra.transports,
+            },
+        });
+        if (!verification.verified) {
+            // Audit log: failed authentication. operatorDid is the user who owns the credential.
+            // Note: error reason is not recorded to avoid leaking internal details to log readers.
+            await this.store.createAuditLog({
+                action: "user.login_failed",
+                operatorDid: stored.userDid,
+                metadata: { source: "passkey", credentialId, domain: hostname },
+                ip,
+                instanceDid,
+            });
+            return errorResponse("Authentication verification failed");
+        }
+        // Update counter and last login
+        await this.store.updateCounter(stored.did, verification.authenticationInfo.newCounter);
+        await this.store.updateLastLogin(stored.userDid, ip, hostname);
+        await ensureInstanceMembership(this.store, stored.userDid, instanceDid);
+        const user = await this.store.getUserByDid(stored.userDid);
+        // Resolve role: prefer instance membership role over global users.role
+        let role = user?.role ?? "guest";
+        if (instanceDid) {
+            const membership = await this.store.getMembership(stored.userDid, instanceDid);
+            if (membership?.role) {
+                role = membership.role;
+            }
+            else if (role !== "owner" && role !== "admin") {
+                role = "guest";
+            }
+        }
+        // Audit log: login. We probe checkLoginAccess here to populate accessBlocked
+        // metadata. The actual access enforcement happens inside issueJWT() below
+        // (this double-call is intentional and cheap; the helper is read-only).
+        const access = await checkLoginAccess(this.store, instanceDid, role);
+        await this.store.createAuditLog({
+            action: "user.login",
+            operatorDid: stored.userDid,
+            metadata: {
+                source: "passkey",
+                domain: hostname,
+                accessBlocked: !access.allowed,
+                blockReason: access.allowed ? undefined : access.reason,
+            },
+            ip,
+            instanceDid,
+        });
+        return this.issueJWT(stored.userDid, stored.pk ?? "", user?.fullName ?? undefined, role, cookieDomain, request, "passkey", instanceDid);
+    }
+    /** Clear auth cookie. GET → redirect to return_to or Referer, POST → JSON response. */
+    logout(request) {
+        // Fire-and-forget: write user.logout audit log without blocking response
+        this.verify(request).then((identity) => {
+            if (identity?.did) {
+                const ip = request.headers.get("CF-Connecting-IP") ?? undefined;
+                this.store.createAuditLog({
+                    action: "user.logout",
+                    operatorDid: identity.did,
+                    ip,
+                }).catch(() => { });
+            }
+        }).catch(() => { });
+        const cookieDomain = this.rpID ? this.getRPID(request) : undefined;
+        const isSecure = new URL(request.url).protocol === "https:";
+        const securePart = isSecure ? " Secure;" : "";
+        let clearCookie = `${this.cookieName}=; Path=/;${securePart} SameSite=Lax; Max-Age=0`;
+        if (cookieDomain?.includes("."))
+            clearCookie += `; Domain=${cookieDomain}`;
+        if (request.method === "GET") {
+            const url = new URL(request.url);
+            const returnTo = url.searchParams.get("return_to") || request.headers.get("Referer") || "/";
+            // Only allow same-origin redirects to prevent open redirect (reject protocol-relative //evil.com)
+            let redirectUrl = "/";
+            try {
+                const parsed = new URL(returnTo, url.origin);
+                if (parsed.origin === url.origin)
+                    redirectUrl = parsed.pathname + parsed.search + parsed.hash;
+            }
+            catch { /* invalid URL → fallback to / */ }
+            return new Response(null, {
+                status: 302,
+                headers: {
+                    Location: redirectUrl,
+                    "Set-Cookie": clearCookie,
+                    "Cache-Control": "private, no-store",
+                },
+            });
+        }
+        return jsonResponse({ ok: true }, 200, { "Set-Cookie": clearCookie });
+    }
+    // ─── Registration eligibility ──────────────────────────────────────
+    /**
+     * Determine if passkey registration should be allowed.
+     *
+     * Returns `{ allowed: true }` if ANY of:
+     *   1. No users exist (first user becomes owner)
+     *   2. Default access policy is "public"
+     *   3. A valid invitation is presented
+     *
+     * Otherwise returns `{ allowed: false, reason, method }` for audit logging.
+     */
+    async checkRegistrationEligibility(invitationId, instanceDid) {
+        const userCount = await this.store.getUserCount();
+        if (userCount === 0)
+            return { allowed: true };
+        const isOpen = await this.store.isRegistrationOpen(instanceDid);
+        if (isOpen)
+            return { allowed: true };
+        if (invitationId) {
+            const invitation = await this.store.getInvitation(invitationId);
+            if (!invitation) {
+                return { allowed: false, reason: "invitation_not_found", method: "invite" };
+            }
+            if (invitation.status !== "active") {
+                return { allowed: false, reason: `invitation_${invitation.status}`, method: "invite" };
+            }
+            if (new Date(invitation.expireAt) <= new Date()) {
+                return { allowed: false, reason: "invitation_expired", method: "invite" };
+            }
+            if (invitation.useCount >= invitation.maxUses) {
+                return { allowed: false, reason: "invitation_exhausted", method: "invite" };
+            }
+            // Valid invitation
+            return { allowed: true };
+        }
+        return { allowed: false, reason: "registration_closed", method: "direct" };
+    }
+    // ─── Passkey Connect/Disconnect (for logged-in users) ───────────────
+    /** POST /connect/register — generate registration options for adding a passkey to an existing account. */
+    async handleConnectRegister(request) {
+        const caller = await this.verifyFull(request);
+        if (!caller)
+            return errorResponse("Authentication required", 401);
+        const rpID = this.getRPID(request);
+        const challengeId = crypto.randomUUID();
+        const challenge = crypto.randomUUID();
+        await this.store.saveChallenge(challengeId, challenge);
+        this.store.purgeExpiredChallenges().catch(() => { });
+        // Exclude existing passkey credential IDs to prevent re-registration
+        const existingPasskeys = await this.store.getConnectedAccountsByProviderAndUser("passkey", caller.did);
+        const excludeCredentials = existingPasskeys
+            .filter((p) => p.id != null)
+            .map((p) => ({
+            id: p.id,
+            type: "public-key",
+        }));
+        const options = await generateChallengeOptions({
+            rpID,
+            rpName: this.rpName,
+            challenge,
+            excludeCredentials,
+        });
+        return jsonResponse({
+            ...options.registration,
+            challengeId,
+        });
+    }
+    /** POST /connect/verify — verify registration credential and bind passkey to existing user. */
+    async handleConnectVerify(request, instanceDid) {
+        const caller = await this.verifyFull(request);
+        if (!caller)
+            return errorResponse("Authentication required", 401);
+        const body = (await request.json());
+        const { challengeId, credential } = body;
+        if (!challengeId || !credential) {
+            return errorResponse("Missing required fields");
+        }
+        const userName = sanitizeName(body.name);
+        const stored = await this.store.getChallenge(challengeId);
+        if (!stored) {
+            return errorResponse("Invalid or expired challenge");
+        }
+        await this.store.deleteChallenge(challengeId);
+        const { challenge } = stored;
+        const rpID = this.getRPID(request);
+        const requestUrl = new URL(request.url);
+        const origin = request.headers.get("Origin") || requestUrl.origin;
+        const ip = request.headers.get("CF-Connecting-IP") ?? undefined;
+        const hostname = requestUrl.hostname;
+        try {
+            const verification = await verifyRegistration({
+                response: credential,
+                expectedChallenge: challenge,
+                expectedOrigin: origin,
+                expectedRPID: rpID,
+            });
+            if (!verification.verified || !verification.registrationInfo) {
+                return errorResponse("Registration verification failed");
+            }
+            const { credential: regCredential, credentialDeviceType, credentialBackedUp } = verification.registrationInfo;
+            const credentialId = regCredential.id;
+            const publicKeyBytes = regCredential.publicKey;
+            const pkBase64 = uint8ArrayToBase64(publicKeyBytes);
+            const passkeyDid = derivePasskeyDID(publicKeyBytes);
+            const transports = credential?.response
+                ?.transports;
+            // Bind to existing user — do NOT create a new user
+            await this.store.createConnectedAccount({
+                did: passkeyDid,
+                pk: pkBase64,
+                userDid: caller.did,
+                provider: "passkey",
+                id: credentialId,
+                extra: JSON.stringify({
+                    transports,
+                    rpID,
+                    credentialDeviceType,
+                    credentialBackedUp,
+                }),
+                userInfo: JSON.stringify({ name: userName || "Passkey" }),
+                ip,
+            });
+            await this.store.incrementPasskeyCount(caller.did);
+            await this.store.createAuditLog({
+                action: "passkey.connect",
+                operatorDid: caller.did,
+                metadata: { passkeyDid, domain: hostname },
+                ip,
+                instanceDid,
+            });
+            return jsonResponse({ ok: true, did: passkeyDid });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Registration verification failed";
+            return errorResponse(message);
+        }
+    }
+    /** POST /disconnect — remove a passkey from the current user. */
+    async handlePasskeyDisconnect(request, instanceDid) {
+        const caller = await this.verifyFull(request);
+        if (!caller)
+            return errorResponse("Authentication required", 401);
+        let body;
+        try {
+            body = await request.json();
+        }
+        catch {
+            return errorResponse("Invalid request body");
+        }
+        const passkeyDid = body?.did;
+        if (!passkeyDid)
+            return errorResponse("Missing passkey DID");
+        // Verify this passkey belongs to the current user
+        const account = await this.store.getConnectedAccountByDid(passkeyDid);
+        if (!account || account.userDid !== caller.did) {
+            return errorResponse("Passkey not found", 404);
+        }
+        // sourceProvider protection: cannot remove last passkey if registered via passkey
+        const user = await this.store.getUserByDid(caller.did);
+        if (user?.sourceProvider === "passkey") {
+            const allPasskeys = await this.store.getConnectedAccountsByProviderAndUser("passkey", caller.did);
+            if (allPasskeys.length <= 1) {
+                return errorResponse("Cannot remove your last passkey (registration provider)", 403);
+            }
+        }
+        await this.store.deleteConnectedAccount(passkeyDid);
+        await this.store.decrementPasskeyCount(caller.did);
+        const ip = request.headers.get("CF-Connecting-IP") ?? undefined;
+        await this.store.createAuditLog({
+            action: "passkey.disconnect",
+            operatorDid: caller.did,
+            metadata: { passkeyDid },
+            ip,
+            instanceDid,
+        });
+        return jsonResponse({ ok: true });
+    }
+    /** POST /rename — rename a passkey belonging to the current user. */
+    async handlePasskeyRename(request, instanceDid) {
+        const caller = await this.verifyFull(request);
+        if (!caller)
+            return errorResponse("Authentication required", 401);
+        let body;
+        try {
+            body = await request.json();
+        }
+        catch {
+            return errorResponse("Invalid request body");
+        }
+        const passkeyDid = body?.did;
+        const newName = sanitizeName(body?.name);
+        if (!passkeyDid)
+            return errorResponse("Missing passkey DID");
+        if (!newName)
+            return errorResponse("Missing name");
+        const account = await this.store.getConnectedAccountByDid(passkeyDid);
+        if (!account || account.userDid !== caller.did) {
+            return errorResponse("Passkey not found", 404);
+        }
+        await this.store.updateConnectedAccountName(passkeyDid, newName);
+        await this.store.createAuditLog({
+            action: "passkey.rename",
+            operatorDid: caller.did,
+            metadata: { passkeyDid, newName },
+            ip: request.headers.get("CF-Connecting-IP") ?? undefined,
+            instanceDid,
+        });
+        return jsonResponse({ ok: true });
+    }
+    // ─── Helpers ────────────────────────────────────────────────────────
+    async issueJWT(did, pk, displayName, role, cookieDomain, request, provider = "passkey", instanceDid) {
+        // Check access rules before issuing JWT
+        const access = await checkLoginAccess(this.store, instanceDid, role ?? "guest");
+        if (!access.allowed) {
+            return jsonResponse({ ok: false, error: access.reason, code: "FORBIDDEN" }, 403);
+        }
+        const payload = {
+            type: "user",
+            did,
+            pk,
+            role: role ?? "guest",
+            provider,
+            kyc: 0,
+            elevated: false,
+        };
+        if (displayName)
+            payload.fullName = displayName;
+        const token = await signJWT(payload, this.jwtSecret, this.jwtExpiresIn);
+        const maxAge = this.jwtExpiresIn;
+        const isSecure = !request || new URL(request.url).protocol === "https:";
+        const securePart = isSecure ? " Secure;" : "";
+        let cookie = `${this.cookieName}=${token}; Path=/;${securePart} SameSite=Lax; Max-Age=${maxAge}`;
+        if (cookieDomain?.includes("."))
+            cookie += `; Domain=${cookieDomain}`;
+        return jsonResponse({ ok: true, verified: true, sessionToken: token, refreshToken: token, did }, 200, { "Set-Cookie": cookie });
+    }
+    /**
+     * Resolve challenge from either challengeId (admin UI) or base64-encoded challenge value (Connect SDK).
+     * Connect SDK sends ?challenge=<base64url(uuid)>, BS stores challenge as raw UUID.
+     */
+    async resolveChallenge(challengeId, challengeParam) {
+        // 1. Try by challengeId (our admin UI sends this)
+        if (challengeId) {
+            const stored = await this.store.getChallenge(challengeId);
+            if (stored)
+                return { id: challengeId, ...stored };
+        }
+        // 2. Try by challenge value from query param (Connect SDK)
+        if (challengeParam) {
+            // SDK sends base64url-encoded challenge — try decoding
+            let decoded = challengeParam;
+            try {
+                const padded = challengeParam.replace(/-/g, "+").replace(/_/g, "/");
+                decoded = atob(padded);
+            }
+            catch { /* not valid base64, use as-is */ }
+            const row = await this.store.getChallengeByValue(decoded);
+            if (row)
+                return row;
+            // Also try the raw (non-decoded) value
+            if (decoded !== challengeParam) {
+                const row2 = await this.store.getChallengeByValue(challengeParam);
+                if (row2)
+                    return row2;
+            }
+        }
+        return null;
+    }
+    getRPID(request) {
+        if (typeof this.rpID === "function")
+            return this.rpID(request);
+        if (this.rpID) {
+            // WebAuthn RP IDs must not include a port number.
+            // X-Arc-Domain may arrive as "localhost:8787" in local dev — strip the port.
+            try {
+                return new URL(`https://${this.rpID}`).hostname;
+            }
+            catch {
+                return this.rpID;
+            }
+        }
+        return new URL(request.url).hostname;
+    }
+    extractCookie(cookieHeader) {
+        const prefix = `${this.cookieName}=`;
+        const cookies = cookieHeader.split(";");
+        for (const cookie of cookies) {
+            const trimmed = cookie.trim();
+            if (trimmed.startsWith(prefix)) {
+                return trimmed.slice(prefix.length);
+            }
+        }
+        return null;
+    }
+}
+function uint8ArrayToBase64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+function base64ToUint8Array(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+//# sourceMappingURL=passkey-handler.js.map