@soulcraft/sdk 1.0.0

package/dist/modules/ai/types.d.ts

@@ -0,0 +1,216 @@
+/**
+ * @module modules/ai/types
+ * @description Type definitions for `sdk.ai.*` — the Claude AI integration module.
+ *
+ * Wraps the Anthropic Claude API with Soulcraft-specific defaults:
+ * - Canonical model IDs for each tier (haiku for speed, sonnet for quality, opus for complex)
+ * - Structured tool call handling with full type safety
+ * - Streaming support via async iteration
+ *
+ * The AI module does not depend on any particular transport — it calls the
+ * Anthropic API directly from the server process and is not proxied through Brainy.
+ */
+/**
+ * Canonical Anthropic model IDs for each Soulcraft platform tier.
+ *
+ * Use these constants instead of hardcoding model strings to ensure consistency
+ * across products and easier future upgrades.
+ */
+export declare const AI_MODELS: {
+    /** Fast, affordable — routine lookups, data extraction, simple Q&A. */
+    readonly haiku: "claude-haiku-4-5-20251001";
+    /** Balanced — most kit operations, content generation, analysis. */
+    readonly sonnet: "claude-sonnet-4-6";
+    /** Most capable — complex reasoning, long-form synthesis, multi-step planning. */
+    readonly opus: "claude-opus-4-6";
+};
+/** A valid Soulcraft Claude model tier ID. */
+export type AiModel = typeof AI_MODELS[keyof typeof AI_MODELS] | string;
+/**
+ * A single message in a Claude conversation.
+ */
+export interface AiMessage {
+    /** The role of the message author. */
+    role: 'user' | 'assistant';
+    /**
+     * The message content.
+     *
+     * For simple text: a plain string.
+     * For tool results: an array of content blocks (see Anthropic API docs).
+     */
+    content: string | AiContentBlock[];
+}
+/**
+ * A content block within a message — text, image, tool use, or tool result.
+ */
+export type AiContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+};
+/**
+ * A tool that Claude can call during a completion.
+ */
+export interface AiTool {
+    /** Machine-readable tool name (snake_case). */
+    name: string;
+    /** Human-readable description used by Claude to decide when to call this tool. */
+    description: string;
+    /** JSON Schema for the tool's input parameters. */
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * A tool call emitted by Claude in a completion response.
+ */
+export interface AiToolCall {
+    /** Unique ID for this tool call (used when feeding results back). */
+    id: string;
+    /** The name of the tool to call. */
+    name: string;
+    /** The arguments Claude wants to pass to the tool. */
+    input: Record<string, unknown>;
+}
+/**
+ * Options for a single Claude completion request.
+ */
+export interface AiCompleteOptions {
+    /** The conversation history, alternating user/assistant messages. */
+    messages: AiMessage[];
+    /**
+     * System prompt injected before the conversation.
+     * Typically derived from `kit.shared.aiPersona` for kit applications.
+     */
+    systemPrompt?: string;
+    /**
+     * The Claude model to use.
+     *
+     * @default AI_MODELS.sonnet
+     */
+    model?: AiModel;
+    /**
+     * Tools available to Claude during this completion.
+     *
+     * When Claude calls a tool, the response will include `toolCalls` instead of
+     * (or in addition to) `text`. The caller is responsible for executing the
+     * tool and continuing the conversation.
+     */
+    tools?: AiTool[];
+    /**
+     * Maximum tokens in the response.
+     *
+     * @default 8192
+     */
+    maxTokens?: number;
+    /**
+     * Temperature for sampling (0–1). Lower = more deterministic.
+     *
+     * @default 1 (Anthropic default)
+     */
+    temperature?: number;
+}
+/**
+ * The result of a single Claude completion.
+ *
+ * `text` and `toolCalls` may both be present if Claude includes a text
+ * explanation alongside tool invocations.
+ */
+export interface AiCompleteResult {
+    /** The text portion of Claude's response, if any. */
+    text: string | null;
+    /** Tool calls Claude wants to make, if any. */
+    toolCalls: AiToolCall[] | null;
+    /** The reason Claude stopped generating. */
+    stopReason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | string;
+    /** Token usage for billing/metering. */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/**
+ * Options for a streaming Claude completion.
+ *
+ * Extends {@link AiCompleteOptions} — same fields apply.
+ */
+export type AiStreamOptions = AiCompleteOptions;
+/**
+ * A single event emitted by a streaming Claude completion.
+ */
+export type AiStreamEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    toolCall: AiToolCall;
+} | {
+    type: 'done';
+    result: AiCompleteResult;
+};
+/**
+ * The `sdk.ai` namespace.
+ *
+ * Provides direct access to Claude for kit applications and product backends.
+ * Handles model selection, tool calls, and streaming without boilerplate.
+ *
+ * @example Basic completion
+ * ```typescript
+ * const response = await sdk.ai.complete({
+ *   messages: [{ role: 'user', content: 'What candles are low in stock?' }],
+ *   systemPrompt: kit.shared.aiPersona,
+ *   model: 'claude-haiku-4-5-20251001',
+ *   tools: [searchInventoryTool],
+ * })
+ *
+ * if (response.toolCalls) {
+ *   for (const call of response.toolCalls) {
+ *     // execute tool and continue conversation
+ *   }
+ * }
+ * ```
+ *
+ * @example Streaming
+ * ```typescript
+ * for await (const event of sdk.ai.stream({ messages, systemPrompt })) {
+ *   if (event.type === 'text') process.stdout.write(event.text)
+ *   if (event.type === 'done') console.log('Tokens:', event.result.usage)
+ * }
+ * ```
+ */
+export interface AiModule {
+    /**
+     * Run a single Claude completion and return the full result.
+     *
+     * @param options - Completion options including messages, model, and tools.
+     * @returns The full completion result with text and/or tool calls.
+     * @throws {Error} If the Anthropic API returns an error.
+     */
+    complete(options: AiCompleteOptions): Promise<AiCompleteResult>;
+    /**
+     * Run a streaming Claude completion, yielding events as they arrive.
+     *
+     * @param options - Completion options (same as {@link AiModule.complete}).
+     * @returns An async iterable of stream events ending with a `done` event.
+     * @throws {Error} If the Anthropic API returns an error.
+     */
+    stream(options: AiStreamOptions): AsyncIterable<AiStreamEvent>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/modules/ai/types.d.ts.map

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

package/dist/modules/ai/types.js

@@ -0,0 +1,30 @@
+/**
+ * @module modules/ai/types
+ * @description Type definitions for `sdk.ai.*` — the Claude AI integration module.
+ *
+ * Wraps the Anthropic Claude API with Soulcraft-specific defaults:
+ * - Canonical model IDs for each tier (haiku for speed, sonnet for quality, opus for complex)
+ * - Structured tool call handling with full type safety
+ * - Streaming support via async iteration
+ *
+ * The AI module does not depend on any particular transport — it calls the
+ * Anthropic API directly from the server process and is not proxied through Brainy.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Model tiers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Canonical Anthropic model IDs for each Soulcraft platform tier.
+ *
+ * Use these constants instead of hardcoding model strings to ensure consistency
+ * across products and easier future upgrades.
+ */
+export const AI_MODELS = {
+    /** Fast, affordable — routine lookups, data extraction, simple Q&A. */
+    haiku: 'claude-haiku-4-5-20251001',
+    /** Balanced — most kit operations, content generation, analysis. */
+    sonnet: 'claude-sonnet-4-6',
+    /** Most capable — complex reasoning, long-form synthesis, multi-step planning. */
+    opus: 'claude-opus-4-6',
+};
+//# sourceMappingURL=types.js.map

package/dist/modules/ai/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/ai/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,uEAAuE;IACvE,KAAK,EAAE,2BAA2B;IAClC,oEAAoE;IACpE,MAAM,EAAE,mBAAmB;IAC3B,kFAAkF;IAClF,IAAI,EAAE,iBAAiB;CACf,CAAA"}

package/dist/modules/auth/backchannel.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @module modules/auth/backchannel
+ * @description OIDC back-channel logout handler factory for Soulcraft product backends.
+ *
+ * Implements the OpenID Connect Back-Channel Logout 1.0 specification. When a user
+ * signs out of the central IdP (`auth.soulcraft.com`), the IdP POSTs a signed
+ * `logout_token` (HS256 JWT) to every registered product's back-channel logout
+ * endpoint. This handler verifies the token and deletes all active sessions for
+ * the identified user, ensuring immediate logout across all products.
+ *
+ * ## Protocol
+ *
+ * 1. IdP POSTs `application/x-www-form-urlencoded` body with `logout_token` field
+ * 2. Handler verifies HS256 JWT signature using the OIDC client secret
+ * 3. Handler validates standard claims: `iss`, `aud`, `events` (must contain
+ *    `http://schemas.openid.net/event/backchannel-logout`)
+ * 4. Handler deletes all better-auth sessions for the `sub` (user ID) claim
+ * 5. Returns 200 on success, 400 for malformed tokens, 401 for bad signatures
+ *
+ * ## Mounting (Hono)
+ *
+ * ```typescript
+ * import { createBackchannelLogoutHandler } from '@soulcraft/sdk/server'
+ *
+ * app.post('/api/auth/backchannel-logout', createBackchannelLogoutHandler({
+ *   auth,
+ *   clientSecret: process.env.SOULCRAFT_OIDC_CLIENT_SECRET!,
+ *   idpUrl: process.env.SOULCRAFT_IDP_URL!,
+ *   clientId: process.env.SOULCRAFT_OIDC_CLIENT_ID!,
+ * }))
+ * ```
+ */
+import type { Context } from 'hono';
+/** Minimal better-auth API surface needed for session deletion. */
+export interface BackchannelAuthLike {
+    api: {
+        revokeUserSessions(opts: {
+            body: {
+                userId: string;
+            };
+            headers?: Headers;
+        }): Promise<unknown>;
+    };
+}
+/**
+ * @description Configuration for createBackchannelLogoutHandler().
+ */
+export interface BackchannelLogoutConfig {
+    /** The product's better-auth instance (used to delete sessions). */
+    auth: BackchannelAuthLike;
+    /** This product's OIDC client secret — used to verify the logout_token signature. */
+    clientSecret: string;
+    /** The central IdP base URL — used to validate the `iss` claim. */
+    idpUrl: string;
+    /** This product's OIDC client ID — used to validate the `aud` claim. */
+    clientId: string;
+}
+/**
+ * @description Creates a Hono route handler for the OIDC back-channel logout endpoint.
+ *
+ * Mount at `POST /api/auth/backchannel-logout`. The handler:
+ * 1. Parses the `logout_token` from the form-encoded body
+ * 2. Verifies the HS256 JWT signature using the OIDC client secret
+ * 3. Validates `iss` (must match idpUrl), `aud` (must match clientId),
+ *    and `events` (must contain the back-channel logout event URI)
+ * 4. Calls `auth.api.revokeUserSessions({ body: { userId: sub } })` to
+ *    immediately invalidate all sessions for the identified user
+ * 5. Returns 200 on success, 400 for malformed/missing token, 401 for
+ *    invalid signature or failed claims validation
+ *
+ * @param config - Auth instance, client secret, IdP URL, and client ID.
+ * @returns A Hono-compatible request handler function.
+ *
+ * @example
+ * ```typescript
+ * app.post('/api/auth/backchannel-logout', createBackchannelLogoutHandler({
+ *   auth,
+ *   clientSecret: process.env.SOULCRAFT_OIDC_CLIENT_SECRET!,
+ *   idpUrl: process.env.SOULCRAFT_IDP_URL!,
+ *   clientId: process.env.SOULCRAFT_OIDC_CLIENT_ID!,
+ * }))
+ * ```
+ */
+export declare function createBackchannelLogoutHandler(config: BackchannelLogoutConfig): (c: Context) => Promise<Response>;
+//# sourceMappingURL=backchannel.d.ts.map

package/dist/modules/auth/backchannel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backchannel.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/backchannel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAMnC,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE;QACH,kBAAkB,CAAC,IAAI,EAAE;YAAE,IAAI,EAAE;gBAAE,MAAM,EAAE,MAAM,CAAA;aAAE,CAAC;YAAC,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;KAC5F,CAAA;CACF;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,IAAI,EAAE,mBAAmB,CAAA;IACzB,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAA;IACpB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAA;IACd,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;CACjB;AA0ED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,uBAAuB,GAC9B,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAgEnC"}

package/dist/modules/auth/backchannel.js

@@ -0,0 +1,168 @@
+/**
+ * @module modules/auth/backchannel
+ * @description OIDC back-channel logout handler factory for Soulcraft product backends.
+ *
+ * Implements the OpenID Connect Back-Channel Logout 1.0 specification. When a user
+ * signs out of the central IdP (`auth.soulcraft.com`), the IdP POSTs a signed
+ * `logout_token` (HS256 JWT) to every registered product's back-channel logout
+ * endpoint. This handler verifies the token and deletes all active sessions for
+ * the identified user, ensuring immediate logout across all products.
+ *
+ * ## Protocol
+ *
+ * 1. IdP POSTs `application/x-www-form-urlencoded` body with `logout_token` field
+ * 2. Handler verifies HS256 JWT signature using the OIDC client secret
+ * 3. Handler validates standard claims: `iss`, `aud`, `events` (must contain
+ *    `http://schemas.openid.net/event/backchannel-logout`)
+ * 4. Handler deletes all better-auth sessions for the `sub` (user ID) claim
+ * 5. Returns 200 on success, 400 for malformed tokens, 401 for bad signatures
+ *
+ * ## Mounting (Hono)
+ *
+ * ```typescript
+ * import { createBackchannelLogoutHandler } from '@soulcraft/sdk/server'
+ *
+ * app.post('/api/auth/backchannel-logout', createBackchannelLogoutHandler({
+ *   auth,
+ *   clientSecret: process.env.SOULCRAFT_OIDC_CLIENT_SECRET!,
+ *   idpUrl: process.env.SOULCRAFT_IDP_URL!,
+ *   clientId: process.env.SOULCRAFT_OIDC_CLIENT_ID!,
+ * }))
+ * ```
+ */
+// The OIDC back-channel logout events claim URI.
+const BACKCHANNEL_LOGOUT_EVENT = 'http://schemas.openid.net/event/backchannel-logout';
+// ─────────────────────────────────────────────────────────────────────────────
+// JWT verification helpers (Web Crypto API — no external deps)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Verify an HS256 JWT using the Web Crypto API.
+ *
+ * @param token - Raw JWT string (`header.payload.signature`).
+ * @param secret - HMAC secret for signature verification.
+ * @returns The decoded payload if the signature is valid, or null.
+ */
+async function verifyHS256JWT(token, secret) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return null;
+    const [headerB64, payloadB64, sigB64] = parts;
+    // Import the HMAC key
+    let key;
+    try {
+        key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    }
+    catch {
+        return null;
+    }
+    // Verify signature over `header.payload`
+    const signingInput = `${headerB64}.${payloadB64}`;
+    let sigBytes;
+    try {
+        sigBytes = Uint8Array.from(atob(sigB64.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0));
+    }
+    catch {
+        return null;
+    }
+    const valid = await crypto.subtle.verify('HMAC', key, sigBytes.buffer, new TextEncoder().encode(signingInput));
+    if (!valid)
+        return null;
+    // Decode payload
+    try {
+        const padded = payloadB64.replace(/-/g, '+').replace(/_/g, '/') +
+            '=='.slice(0, (4 - (payloadB64.length % 4)) % 4);
+        return JSON.parse(atob(padded));
+    }
+    catch {
+        return null;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// createBackchannelLogoutHandler
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * @description Creates a Hono route handler for the OIDC back-channel logout endpoint.
+ *
+ * Mount at `POST /api/auth/backchannel-logout`. The handler:
+ * 1. Parses the `logout_token` from the form-encoded body
+ * 2. Verifies the HS256 JWT signature using the OIDC client secret
+ * 3. Validates `iss` (must match idpUrl), `aud` (must match clientId),
+ *    and `events` (must contain the back-channel logout event URI)
+ * 4. Calls `auth.api.revokeUserSessions({ body: { userId: sub } })` to
+ *    immediately invalidate all sessions for the identified user
+ * 5. Returns 200 on success, 400 for malformed/missing token, 401 for
+ *    invalid signature or failed claims validation
+ *
+ * @param config - Auth instance, client secret, IdP URL, and client ID.
+ * @returns A Hono-compatible request handler function.
+ *
+ * @example
+ * ```typescript
+ * app.post('/api/auth/backchannel-logout', createBackchannelLogoutHandler({
+ *   auth,
+ *   clientSecret: process.env.SOULCRAFT_OIDC_CLIENT_SECRET!,
+ *   idpUrl: process.env.SOULCRAFT_IDP_URL!,
+ *   clientId: process.env.SOULCRAFT_OIDC_CLIENT_ID!,
+ * }))
+ * ```
+ */
+export function createBackchannelLogoutHandler(config) {
+    const idpOrigin = config.idpUrl.replace(/\/$/, '');
+    return async function backchannelLogoutHandler(c) {
+        // Parse the logout_token from the form-encoded body
+        let logoutToken = null;
+        try {
+            const contentType = c.req.header('content-type') ?? '';
+            if (contentType.includes('application/x-www-form-urlencoded')) {
+                const body = await c.req.parseBody();
+                logoutToken = body['logout_token'] ?? null;
+            }
+            else {
+                // Also accept JSON body for easier testing
+                const body = await c.req.json();
+                logoutToken = body['logout_token'] ?? null;
+            }
+        }
+        catch {
+            return c.json({ error: 'Failed to parse request body' }, 400);
+        }
+        if (!logoutToken || typeof logoutToken !== 'string') {
+            return c.json({ error: 'Missing logout_token' }, 400);
+        }
+        // Verify the JWT
+        const payload = await verifyHS256JWT(logoutToken, config.clientSecret);
+        if (!payload) {
+            return c.json({ error: 'Invalid logout_token signature' }, 401);
+        }
+        // Validate issuer
+        if (payload['iss'] !== idpOrigin) {
+            return c.json({ error: 'Invalid issuer' }, 401);
+        }
+        // Validate audience — may be a string or array of strings
+        const aud = payload['aud'];
+        const audList = Array.isArray(aud) ? aud : [String(aud ?? '')];
+        if (!audList.includes(config.clientId)) {
+            return c.json({ error: 'Invalid audience' }, 401);
+        }
+        // Validate events claim
+        const events = payload['events'];
+        if (!events || !(BACKCHANNEL_LOGOUT_EVENT in events)) {
+            return c.json({ error: 'Missing backchannel logout event' }, 400);
+        }
+        // Extract the subject user ID
+        const sub = payload['sub'];
+        if (!sub || typeof sub !== 'string') {
+            return c.json({ error: 'Missing sub claim' }, 400);
+        }
+        // Revoke all sessions for this user
+        try {
+            await config.auth.api.revokeUserSessions({ body: { userId: sub } });
+        }
+        catch (err) {
+            console.error(`[SDK/backchannel] Failed to revoke sessions for user ${sub}:`, err);
+            return c.json({ error: 'Failed to revoke sessions' }, 500);
+        }
+        return c.json({ ok: true }, 200);
+    };
+}
+//# sourceMappingURL=backchannel.js.map

package/dist/modules/auth/backchannel.js.map

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

package/dist/modules/auth/config.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @module modules/auth/config
+ * @description Shared constants, utilities, and environment helpers for Soulcraft
+ * platform authentication.
+ *
+ * Provides ONLY well-typed shared values — no `betterAuth()` wrappers. Each product
+ * (Workshop, Venue, Academy) assembles its own fully-typed `betterAuth()` configuration
+ * using these constants and utilities, keeping TypeScript inference intact end-to-end.
+ *
+ * ## Why no config factory functions?
+ *
+ * A factory returning a broad object type loses compile-time safety when passed to
+ * `betterAuth()`. The correct boundary is:
+ * - **This module** → exports typed field definitions, session config, and pure utilities
+ * - **Each product** → imports those exports and constructs its own `betterAuth()` call
+ *
+ * This absorbs and replaces `@soulcraft/auth/config`, which is deprecated.
+ *
+ * @example Workshop auth setup
+ * ```typescript
+ * import { betterAuth } from 'better-auth'
+ * import {
+ *   SOULCRAFT_USER_FIELDS,
+ *   SOULCRAFT_SESSION_CONFIG,
+ *   computeEmailHash,
+ * } from '@soulcraft/sdk/server'
+ *
+ * export const auth = betterAuth({
+ *   database: new Database('./auth.db'),
+ *   secret: process.env.BETTER_AUTH_SECRET!,
+ *   session: SOULCRAFT_SESSION_CONFIG,
+ *   user: { additionalFields: SOULCRAFT_USER_FIELDS },
+ *   databaseHooks: {
+ *     user: { create: { before: async (user) => ({
+ *       data: { ...user, emailHash: computeEmailHash(user.email), platformRole: 'creator' }
+ *     })}}
+ *   },
+ * })
+ * ```
+ */
+import type { AuthMode, OIDCClientConfig } from './types.js';
+/**
+ * Additional fields to register on the better-auth `user` table.
+ *
+ * Pass to `betterAuth({ user: { additionalFields: SOULCRAFT_USER_FIELDS } })`.
+ *
+ * `emailHash` must be populated at user-creation time via a
+ * `databaseHooks.user.create.before` hook. `platformRole` defaults to `'creator'`
+ * for Workshop; products override this in their own hook.
+ */
+export declare const SOULCRAFT_USER_FIELDS: {
+    readonly platformRole: {
+        readonly type: "string";
+        readonly required: false;
+        readonly defaultValue: "creator";
+    };
+    readonly emailHash: {
+        readonly type: "string";
+        readonly required: false;
+        readonly defaultValue: "";
+    };
+};
+/**
+ * Session lifetime configuration shared across all Soulcraft products.
+ *
+ * Pass to `betterAuth({ session: SOULCRAFT_SESSION_CONFIG })`.
+ *
+ * - Sessions are valid for 30 days from issuance
+ * - Silently refreshed after 24 hours of activity, resetting the 30-day window
+ */
+export declare const SOULCRAFT_SESSION_CONFIG: {
+    readonly expiresIn: number;
+    readonly updateAge: number;
+};
+/**
+ * Compute the SHA-256 hex digest of a canonical email address.
+ *
+ * The email is lower-cased and trimmed before hashing to ensure the same
+ * input always yields the same digest regardless of capitalisation or whitespace.
+ *
+ * Stored as `emailHash` on the user record. Used by Workshop to deterministically
+ * locate the user's Brainy data directory without exposing the raw email in paths.
+ *
+ * @param email - Raw email address (any case, may have leading/trailing whitespace).
+ * @returns 64-character lowercase hex SHA-256 digest.
+ *
+ * @example
+ * computeEmailHash('Alice@Example.COM') === computeEmailHash('alice@example.com') // true
+ * computeEmailHash('alice@example.com')
+ * // → 'b4c9a289522dd28a04617a41d7b14cf18d43d06febe513d9e27b5da67c17e52e'
+ */
+export declare function computeEmailHash(email: string): string;
+/**
+ * Determine the authentication mode from environment variables.
+ *
+ * - `'standalone'`  — each product runs its own better-auth instance with a local
+ *   SQLite database. No cross-product SSO. Default before `auth.soulcraft.com` is live.
+ * - `'oidc-client'` — set `SOULCRAFT_IDP_URL` to activate. The product's better-auth
+ *   instance delegates all authentication to the central IdP.
+ *
+ * @returns The current auth mode derived from `SOULCRAFT_IDP_URL`.
+ */
+export declare function getAuthMode(): AuthMode;
+/**
+ * Read OIDC client configuration from environment variables.
+ *
+ * Returns `null` in standalone mode (when `SOULCRAFT_IDP_URL` is unset).
+ * Throws with a descriptive message if the URL is set but required variables
+ * are missing — prevents silent misconfiguration.
+ *
+ * | Variable                     | Required | Description                             |
+ * |------------------------------|----------|-----------------------------------------|
+ * | `SOULCRAFT_IDP_URL`          | Yes      | Central IdP base URL                    |
+ * | `SOULCRAFT_OIDC_CLIENT_ID`   | Yes      | This product's registered client ID     |
+ * | `SOULCRAFT_OIDC_CLIENT_SECRET` | Yes    | This product's registered client secret |
+ * | `SOULCRAFT_OIDC_REDIRECT_URI`  | No     | Deprecated — auto-derived from BETTER_AUTH_URL |
+ *
+ * @returns OIDC client config or null in standalone mode.
+ * @throws {Error} If `SOULCRAFT_IDP_URL` is set but client ID or secret are missing.
+ */
+export declare function getOIDCClientConfig(): OIDCClientConfig | null;
+//# sourceMappingURL=config.d.ts.map

package/dist/modules/auth/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAM5D;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;CAWxB,CAAA;AAMV;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;;;CAG3B,CAAA;AAMV;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAItD;AAMD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAuB7D"}