@soulcraft/sdk 1.6.2 → 2.0.0

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

@@ -0,0 +1,208 @@
+/**
+ * @module modules/auth/products
+ * @description Centralized registry of all Soulcraft platform products and their
+ * auth configuration. This is the single source of truth for:
+ *
+ * - Which products exist on the platform
+ * - Their production domains and local dev ports
+ * - Their OIDC client IDs and redirect callback paths
+ * - Whether they require backchannel logout support
+ * - Which env var holds their OIDC client secret
+ *
+ * The auth server (`auth.soulcraft.com`) consumes this registry to derive all
+ * its registration arrays — trusted origins, CORS, OIDC trusted clients, and
+ * backchannel logout recipients — instead of maintaining five parallel hardcoded lists.
+ *
+ * ## Adding a new product
+ *
+ * 1. Add an entry to `SOULCRAFT_PRODUCTS` below (TypeScript enforces completeness).
+ * 2. Add `{PRODUCT}_OIDC_CLIENT_SECRET` (or equivalent) to the auth server's
+ *    `.env.production`. Generate with: `openssl rand -hex 32`
+ * 3. Publish a new version of `@soulcraft/sdk`.
+ * 4. Deploy the auth server — it will pick up the new product automatically.
+ * 5. Set `SOULCRAFT_IDP_URL` in the product's own `.env.production`.
+ *
+ * @see ADR-002-product-registry.md for design rationale.
+ */
+/**
+ * Full auth configuration for a single Soulcraft platform product.
+ *
+ * Consumed by the auth server to derive trusted origins, CORS origins, OIDC
+ * client registrations, and backchannel logout recipients.
+ */
+export interface ProductRegistration {
+    /** Human-readable display name, e.g. `"Soulcraft Workshop"`. */
+    name: string;
+    /**
+     * Production domain without scheme or trailing slash.
+     * e.g. `"workshop.soulcraft.com"`, `"soulcraft.com"`
+     */
+    domain: string;
+    /** Local development port. Used to derive `http://localhost:{devPort}` origins. */
+    devPort: number;
+    /**
+     * OIDC client ID registered on the auth server.
+     * Must be unique across all products. e.g. `"workshop"`.
+     */
+    clientId: string;
+    /**
+     * Name of the environment variable that holds this product's OIDC client secret
+     * (or backchannel secret for cookie-proxy products). e.g. `"WORKSHOP_OIDC_CLIENT_SECRET"`.
+     */
+    secretEnvVar: string;
+    /**
+     * How this product authenticates users:
+     * - `'oidc-redirect'` — full OIDC authorization code flow with redirect callbacks
+     * - `'cookie-proxy'` — validates the shared `.soulcraft.com` session cookie directly
+     *   against `GET /api/auth/get-session`; no OIDC redirect involved
+     */
+    authMode: 'oidc-redirect' | 'cookie-proxy';
+    /**
+     * Paths on this product's origin that the auth server should register as OIDC
+     * redirect URIs. Empty array for cookie-proxy products. Both production and dev
+     * variants are derived automatically via `deriveRedirectUrls`.
+     */
+    callbackPaths: string[];
+    /**
+     * Additional paths to include as OIDC redirect URIs beyond the callback paths.
+     * Typically the homepage (`"/"`) which is used as `post_logout_redirect_uri`.
+     * Defaults to `["/"]` when omitted.
+     */
+    extraRedirectPaths?: string[];
+    /**
+     * When `true`, the auth server includes this product in its OIDC backchannel
+     * logout registry. The product's `{domain}/api/auth/backchannel-logout` endpoint
+     * will be notified on every sign-out so it can terminate local sessions immediately.
+     *
+     * Set to `false` only for products that do not implement a backchannel endpoint
+     * (e.g. read-only dashboards, analytics tools).
+     */
+    backchannelRequired: boolean;
+}
+/**
+ * Central registry of all Soulcraft platform products.
+ *
+ * `as const satisfies Record<string, ProductRegistration>` provides two guarantees:
+ * - TypeScript enforces that every entry has all required `ProductRegistration` fields
+ * - Literal types are preserved so `keyof typeof SOULCRAFT_PRODUCTS` yields
+ *   `'workshop' | 'venue' | 'portal' | 'academy' | 'pulse'` (not just `string`)
+ *
+ * Adding a product here automatically:
+ * - Extends the `SoulcraftProduct` union type
+ * - Includes the product in all auth server derivations (origins, CORS, OIDC clients)
+ */
+export declare const SOULCRAFT_PRODUCTS: {
+    readonly workshop: {
+        readonly name: "Soulcraft Workshop";
+        readonly domain: "workshop.soulcraft.com";
+        readonly devPort: 5001;
+        readonly clientId: "workshop";
+        readonly secretEnvVar: "WORKSHOP_OIDC_CLIENT_SECRET";
+        readonly authMode: "oidc-redirect";
+        readonly callbackPaths: ["/api/auth/oauth2/callback/soulcraft-idp", "/api/auth/callback/soulcraft-idp"];
+        readonly extraRedirectPaths: ["/"];
+        readonly backchannelRequired: true;
+    };
+    readonly venue: {
+        readonly name: "Soulcraft Venue";
+        readonly domain: "venue.soulcraft.com";
+        readonly devPort: 5174;
+        readonly clientId: "venue";
+        readonly secretEnvVar: "VENUE_OIDC_CLIENT_SECRET";
+        readonly authMode: "oidc-redirect";
+        readonly callbackPaths: ["/api/auth/callback/soulcraft-idp"];
+        readonly extraRedirectPaths: ["/"];
+        readonly backchannelRequired: true;
+    };
+    readonly portal: {
+        readonly name: "Soulcraft Portal";
+        readonly domain: "soulcraft.com";
+        readonly devPort: 8080;
+        readonly clientId: "portal";
+        readonly secretEnvVar: "PORTAL_OIDC_CLIENT_SECRET";
+        readonly authMode: "oidc-redirect";
+        readonly callbackPaths: ["/api/auth/callback/soulcraft-idp", "/auth/callback"];
+        readonly extraRedirectPaths: ["/"];
+        readonly backchannelRequired: true;
+    };
+    readonly academy: {
+        readonly name: "Soulcraft Academy";
+        readonly domain: "academy.soulcraft.com";
+        readonly devPort: 5002;
+        readonly clientId: "academy";
+        readonly secretEnvVar: "ACADEMY_OIDC_CLIENT_SECRET";
+        readonly authMode: "oidc-redirect";
+        readonly callbackPaths: ["/api/auth/callback/soulcraft-idp"];
+        readonly extraRedirectPaths: ["/"];
+        readonly backchannelRequired: true;
+    };
+    readonly pulse: {
+        readonly name: "Soulcraft Pulse";
+        readonly domain: "pulse.soulcraft.com";
+        readonly devPort: 5004;
+        readonly clientId: "pulse";
+        readonly secretEnvVar: "PULSE_BACKCHANNEL_SECRET";
+        readonly authMode: "cookie-proxy";
+        readonly callbackPaths: [];
+        readonly extraRedirectPaths: ["/"];
+        readonly backchannelRequired: false;
+    };
+};
+/**
+ * Union of all registered Soulcraft product keys.
+ *
+ * Automatically derived from `SOULCRAFT_PRODUCTS` — adding a product to the
+ * registry extends this type without any manual update.
+ *
+ * @example
+ * function validateProduct(p: string): p is SoulcraftProduct {
+ *   return p in SOULCRAFT_PRODUCTS
+ * }
+ */
+export type SoulcraftProduct = keyof typeof SOULCRAFT_PRODUCTS;
+/**
+ * Derive the full list of trusted origins for all registered products.
+ *
+ * Returns both the production HTTPS origin and the `http://localhost:{devPort}`
+ * development origin for every product in `SOULCRAFT_PRODUCTS`.
+ *
+ * Used by the auth server for:
+ * - `betterAuth({ trustedOrigins: deriveOrigins() })` — callback URL validation
+ * - `cors({ origin: deriveOrigins() })` — CORS preflight on the Hono layer
+ *
+ * @returns Deduplicated list of origin strings (scheme + host, no trailing slash).
+ *
+ * @example
+ * deriveOrigins()
+ * // → [
+ * //   'https://workshop.soulcraft.com', 'http://localhost:5001',
+ * //   'https://venue.soulcraft.com',    'http://localhost:5174',
+ * //   'https://soulcraft.com',          'http://localhost:8080',
+ * //   'https://academy.soulcraft.com',  'http://localhost:5002',
+ * //   'https://pulse.soulcraft.com',    'http://localhost:5004',
+ * // ]
+ */
+export declare function deriveOrigins(): string[];
+/**
+ * Derive all OIDC redirect URIs for a single product registration.
+ *
+ * Combines callback paths and extra redirect paths, generating both production
+ * and local development variants for each. Results are ordered: production paths
+ * first (all), then dev paths (all), matching the ordering in the auth server.
+ *
+ * @param p - A `ProductRegistration` from `SOULCRAFT_PRODUCTS`.
+ * @returns List of fully-qualified redirect URI strings.
+ *
+ * @example
+ * deriveRedirectUrls(SOULCRAFT_PRODUCTS.workshop)
+ * // → [
+ * //   'https://workshop.soulcraft.com/api/auth/oauth2/callback/soulcraft-idp',
+ * //   'https://workshop.soulcraft.com/api/auth/callback/soulcraft-idp',
+ * //   'https://workshop.soulcraft.com/',
+ * //   'http://localhost:5001/api/auth/oauth2/callback/soulcraft-idp',
+ * //   'http://localhost:5001/api/auth/callback/soulcraft-idp',
+ * //   'http://localhost:5001/',
+ * // ]
+ */
+export declare function deriveRedirectUrls(p: ProductRegistration): string[];
+//# sourceMappingURL=products.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"products.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/products.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;;;;OAKG;IACH,QAAQ,EAAE,eAAe,GAAG,cAAc,CAAA;IAC1C;;;;OAIG;IACH,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC7B;;;;;;;OAOG;IACH,mBAAmB,EAAE,OAAO,CAAA;CAC7B;AAMD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+DyB,CAAA;AAExD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,kBAAkB,CAAA;AAM9D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAKxC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAQnE"}

package/dist/modules/auth/products.js

@@ -0,0 +1,165 @@
+/**
+ * @module modules/auth/products
+ * @description Centralized registry of all Soulcraft platform products and their
+ * auth configuration. This is the single source of truth for:
+ *
+ * - Which products exist on the platform
+ * - Their production domains and local dev ports
+ * - Their OIDC client IDs and redirect callback paths
+ * - Whether they require backchannel logout support
+ * - Which env var holds their OIDC client secret
+ *
+ * The auth server (`auth.soulcraft.com`) consumes this registry to derive all
+ * its registration arrays — trusted origins, CORS, OIDC trusted clients, and
+ * backchannel logout recipients — instead of maintaining five parallel hardcoded lists.
+ *
+ * ## Adding a new product
+ *
+ * 1. Add an entry to `SOULCRAFT_PRODUCTS` below (TypeScript enforces completeness).
+ * 2. Add `{PRODUCT}_OIDC_CLIENT_SECRET` (or equivalent) to the auth server's
+ *    `.env.production`. Generate with: `openssl rand -hex 32`
+ * 3. Publish a new version of `@soulcraft/sdk`.
+ * 4. Deploy the auth server — it will pick up the new product automatically.
+ * 5. Set `SOULCRAFT_IDP_URL` in the product's own `.env.production`.
+ *
+ * @see ADR-002-product-registry.md for design rationale.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Registry
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Central registry of all Soulcraft platform products.
+ *
+ * `as const satisfies Record<string, ProductRegistration>` provides two guarantees:
+ * - TypeScript enforces that every entry has all required `ProductRegistration` fields
+ * - Literal types are preserved so `keyof typeof SOULCRAFT_PRODUCTS` yields
+ *   `'workshop' | 'venue' | 'portal' | 'academy' | 'pulse'` (not just `string`)
+ *
+ * Adding a product here automatically:
+ * - Extends the `SoulcraftProduct` union type
+ * - Includes the product in all auth server derivations (origins, CORS, OIDC clients)
+ */
+export const SOULCRAFT_PRODUCTS = {
+    workshop: {
+        name: 'Soulcraft Workshop',
+        domain: 'workshop.soulcraft.com',
+        devPort: 5001,
+        clientId: 'workshop',
+        secretEnvVar: 'WORKSHOP_OIDC_CLIENT_SECRET',
+        authMode: 'oidc-redirect',
+        callbackPaths: [
+            '/api/auth/oauth2/callback/soulcraft-idp',
+            // Legacy path kept for in-flight sessions during transitions
+            '/api/auth/callback/soulcraft-idp',
+        ],
+        extraRedirectPaths: ['/'],
+        backchannelRequired: true,
+    },
+    venue: {
+        name: 'Soulcraft Venue',
+        domain: 'venue.soulcraft.com',
+        devPort: 5174,
+        clientId: 'venue',
+        secretEnvVar: 'VENUE_OIDC_CLIENT_SECRET',
+        authMode: 'oidc-redirect',
+        callbackPaths: ['/api/auth/callback/soulcraft-idp'],
+        extraRedirectPaths: ['/'],
+        backchannelRequired: true,
+    },
+    portal: {
+        name: 'Soulcraft Portal',
+        domain: 'soulcraft.com',
+        devPort: 8080,
+        clientId: 'portal',
+        secretEnvVar: 'PORTAL_OIDC_CLIENT_SECRET',
+        authMode: 'oidc-redirect',
+        callbackPaths: ['/api/auth/callback/soulcraft-idp', '/auth/callback'],
+        extraRedirectPaths: ['/'],
+        backchannelRequired: true,
+    },
+    academy: {
+        name: 'Soulcraft Academy',
+        domain: 'academy.soulcraft.com',
+        devPort: 5002,
+        clientId: 'academy',
+        secretEnvVar: 'ACADEMY_OIDC_CLIENT_SECRET',
+        authMode: 'oidc-redirect',
+        callbackPaths: ['/api/auth/callback/soulcraft-idp'],
+        extraRedirectPaths: ['/'],
+        backchannelRequired: true,
+    },
+    pulse: {
+        name: 'Soulcraft Pulse',
+        domain: 'pulse.soulcraft.com',
+        devPort: 5004,
+        clientId: 'pulse',
+        // Pulse uses cookie-proxy; PULSE_BACKCHANNEL_SECRET doubles as the OIDC client
+        // secret for the minimal OIDC client entry that registers the homepage as a valid
+        // post_logout_redirect_uri. Backchannel is best-effort; no startup failure if absent.
+        secretEnvVar: 'PULSE_BACKCHANNEL_SECRET',
+        authMode: 'cookie-proxy',
+        callbackPaths: [],
+        extraRedirectPaths: ['/'],
+        backchannelRequired: false,
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Derivation helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Derive the full list of trusted origins for all registered products.
+ *
+ * Returns both the production HTTPS origin and the `http://localhost:{devPort}`
+ * development origin for every product in `SOULCRAFT_PRODUCTS`.
+ *
+ * Used by the auth server for:
+ * - `betterAuth({ trustedOrigins: deriveOrigins() })` — callback URL validation
+ * - `cors({ origin: deriveOrigins() })` — CORS preflight on the Hono layer
+ *
+ * @returns Deduplicated list of origin strings (scheme + host, no trailing slash).
+ *
+ * @example
+ * deriveOrigins()
+ * // → [
+ * //   'https://workshop.soulcraft.com', 'http://localhost:5001',
+ * //   'https://venue.soulcraft.com',    'http://localhost:5174',
+ * //   'https://soulcraft.com',          'http://localhost:8080',
+ * //   'https://academy.soulcraft.com',  'http://localhost:5002',
+ * //   'https://pulse.soulcraft.com',    'http://localhost:5004',
+ * // ]
+ */
+export function deriveOrigins() {
+    return Object.values(SOULCRAFT_PRODUCTS).flatMap((p) => [
+        `https://${p.domain}`,
+        `http://localhost:${p.devPort}`,
+    ]);
+}
+/**
+ * Derive all OIDC redirect URIs for a single product registration.
+ *
+ * Combines callback paths and extra redirect paths, generating both production
+ * and local development variants for each. Results are ordered: production paths
+ * first (all), then dev paths (all), matching the ordering in the auth server.
+ *
+ * @param p - A `ProductRegistration` from `SOULCRAFT_PRODUCTS`.
+ * @returns List of fully-qualified redirect URI strings.
+ *
+ * @example
+ * deriveRedirectUrls(SOULCRAFT_PRODUCTS.workshop)
+ * // → [
+ * //   'https://workshop.soulcraft.com/api/auth/oauth2/callback/soulcraft-idp',
+ * //   'https://workshop.soulcraft.com/api/auth/callback/soulcraft-idp',
+ * //   'https://workshop.soulcraft.com/',
+ * //   'http://localhost:5001/api/auth/oauth2/callback/soulcraft-idp',
+ * //   'http://localhost:5001/api/auth/callback/soulcraft-idp',
+ * //   'http://localhost:5001/',
+ * // ]
+ */
+export function deriveRedirectUrls(p) {
+    const extraPaths = p.extraRedirectPaths ?? ['/'];
+    const allPaths = [...p.callbackPaths, ...extraPaths];
+    const prod = allPaths.map((path) => `https://${p.domain}${path}`);
+    const dev = allPaths.map((path) => `http://localhost:${p.devPort}${path}`);
+    return [...prod, ...dev];
+}
+//# sourceMappingURL=products.js.map

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

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