@amodalai/runtime 0.3.70 → 0.3.72

package/dist/src/auth/config.js

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Config-driven auth — discriminated union the agent owner sets in
+ * `amodal.json` (or whatever surfaces the runtime through). The host
+ * resolves any `env:` references against its secrets store before
+ * passing the config to `createAuthStrategy(config)`.
+ *
+ *   {
+ *     "auth": {
+ *       "type": "oidc",
+ *       "issuer": "https://acme.okta.com",
+ *       ...
+ *     }
+ *   }
+ */
+import { z } from 'zod';
+const NoneAuthConfigSchema = z.object({
+    type: z.literal('none'),
+    /** Synthesized user id for the anonymous session. Defaults to `'anonymous'`. */
+    userId: z.string().optional(),
+});
+const JwtSecretAuthConfigSchema = z.object({
+    type: z.literal('jwt_secret'),
+    /** Shared HMAC secret used to verify incoming JWTs. */
+    secret: z.string().min(1),
+    /** HMAC algorithm. Defaults to HS256. */
+    algorithm: z.enum(['HS256', 'HS384', 'HS512']).optional(),
+    /** Expected `iss` claim. Optional. */
+    issuer: z.string().optional(),
+    /** Expected `aud` claim. Optional. */
+    audience: z.string().optional(),
+});
+const OidcAuthConfigSchema = z.object({
+    type: z.literal('oidc'),
+    /** OIDC issuer URL — the IdP's discovery base (`https://acme.okta.com`). */
+    issuer: z.string().url(),
+    clientId: z.string().min(1),
+    clientSecret: z.string().min(1),
+    /** Where the IdP redirects back after login. Must be registered with the IdP. */
+    callbackUrl: z.string().url(),
+    /** OAuth scopes to request. Defaults to `['openid', 'email', 'profile']`. */
+    scopes: z.array(z.string()).optional(),
+    /**
+     * HMAC secret used to sign the session JWT stored in the runtime's cookie.
+     * Distinct from the IdP — this is purely the runtime's session signing key.
+     */
+    sessionSecret: z.string().min(16),
+    /** Cookie name for the session JWT. Defaults to `'amodal_session'`. */
+    cookieName: z.string().optional(),
+    /** Session TTL in seconds. Defaults to 24h. */
+    sessionTtlSeconds: z.number().int().positive().optional(),
+});
+const HeaderAuthConfigSchema = z.object({
+    type: z.literal('header'),
+    headerName: z.string().optional(),
+});
+const CustomAuthConfigSchema = z.object({
+    type: z.literal('custom'),
+    /**
+     * Module path (relative to the agent's runtime directory) whose default
+     * export implements the `AuthStrategy` interface. The runtime imports
+     * this file at startup and validates the shape.
+     */
+    module: z.string().min(1),
+});
+/**
+ * "Sign in with Amodal" — verifies platform JWTs minted by the Amodal
+ * cloud (or any self-hosted Amodal-equivalent platform). Agent owners on
+ * the Amodal cloud need zero config; the cloud's deploy pipeline injects
+ * the JWKS URL via the `AMODAL_JWKS_URL` env var. Self-hosters override
+ * via the optional `jwksUrl` field.
+ */
+const AmodalAuthConfigSchema = z.object({
+    type: z.literal('amodal'),
+    jwksUrl: z.string().url().optional(),
+    issuer: z.string().optional(),
+});
+export const AuthConfigSchema = z.discriminatedUnion('type', [
+    NoneAuthConfigSchema,
+    JwtSecretAuthConfigSchema,
+    OidcAuthConfigSchema,
+    HeaderAuthConfigSchema,
+    CustomAuthConfigSchema,
+    AmodalAuthConfigSchema,
+]);
+/**
+ * Parse + validate an `auth` block from agent config. Throws a clear
+ * error on any malformed shape so misconfiguration fails at startup
+ * rather than at first request. Pass `undefined` / missing config to
+ * default to `{type: 'none'}`.
+ */
+export function parseAuthConfig(raw) {
+    if (raw == null)
+        return { type: 'none' };
+    const parsed = AuthConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Invalid auth config: ${parsed.error.errors
+            .map((e) => `${e.path.join('.') || '<root>'}: ${e.message}`)
+            .join('; ')}`);
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=config.js.map

package/dist/src/auth/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/auth/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACvB,gFAAgF;IAChF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAEH,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IAC7B,uDAAuD;IACvD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,yCAAyC;IACzC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzD,sCAAsC;IACtC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,sCAAsC;IACtC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAEH,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACvB,4EAA4E;IAC5E,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACxB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,iFAAiF;IACjF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC7B,6EAA6E;IAC7E,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtC;;;OAGG;IACH,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IACjC,uEAAuE;IACvE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,+CAA+C;IAC/C,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC1D,CAAC,CAAC;AAEH,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACzB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAEH,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACzB;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC1B,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACzB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACpC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAC3D,oBAAoB;IACpB,yBAAyB;IACzB,oBAAoB;IACpB,sBAAsB;IACtB,sBAAsB;IACtB,sBAAsB;CACvB,CAAC,CAAC;AAUH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,EAAC,IAAI,EAAE,MAAM,EAAC,CAAC;IACvC,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,wBAAwB,MAAM,CAAC,KAAK,CAAC,MAAM;aACxC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aAC3D,IAAI,CAAC,IAAI,CAAC,EAAE,CAChB,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/src/auth/config.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};

package/dist/src/auth/config.test.js

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, it, expect } from 'vitest';
+import { parseAuthConfig } from './config.js';
+describe('parseAuthConfig', () => {
+    it('defaults to {type: none} when undefined', () => {
+        expect(parseAuthConfig(undefined)).toEqual({ type: 'none' });
+        expect(parseAuthConfig(null)).toEqual({ type: 'none' });
+    });
+    it('accepts a valid none config', () => {
+        expect(parseAuthConfig({ type: 'none' })).toEqual({ type: 'none' });
+        expect(parseAuthConfig({ type: 'none', userId: 'guest' })).toEqual({
+            type: 'none',
+            userId: 'guest',
+        });
+    });
+    it('accepts a valid jwt_secret config', () => {
+        const cfg = parseAuthConfig({ type: 'jwt_secret', secret: 'sssh' });
+        expect(cfg.type).toBe('jwt_secret');
+    });
+    it('rejects jwt_secret without secret', () => {
+        expect(() => parseAuthConfig({ type: 'jwt_secret' })).toThrow(/secret/);
+    });
+    it('accepts a valid oidc config', () => {
+        const cfg = parseAuthConfig({
+            type: 'oidc',
+            issuer: 'https://acme.okta.com',
+            clientId: 'abc',
+            clientSecret: 'shh',
+            callbackUrl: 'https://agent.example.com/auth/callback',
+            sessionSecret: 'a-secret-of-at-least-16-chars-long',
+        });
+        expect(cfg.type).toBe('oidc');
+    });
+    it('rejects oidc with a non-URL issuer', () => {
+        expect(() => parseAuthConfig({
+            type: 'oidc',
+            issuer: 'not-a-url',
+            clientId: 'a',
+            clientSecret: 'b',
+            callbackUrl: 'https://x.test/cb',
+            sessionSecret: 'a-secret-of-at-least-16-chars-long',
+        })).toThrow(/url/i);
+    });
+    it('rejects oidc with too-short sessionSecret', () => {
+        expect(() => parseAuthConfig({
+            type: 'oidc',
+            issuer: 'https://x.test',
+            clientId: 'a',
+            clientSecret: 'b',
+            callbackUrl: 'https://x.test/cb',
+            sessionSecret: 'short',
+        })).toThrow(/sessionSecret/);
+    });
+    it('accepts custom config with module path', () => {
+        expect(parseAuthConfig({ type: 'custom', module: './my-auth.ts' })).toEqual({
+            type: 'custom',
+            module: './my-auth.ts',
+        });
+    });
+    it('accepts a bare amodal config (zero-config sign-in with Amodal)', () => {
+        expect(parseAuthConfig({ type: 'amodal' })).toEqual({ type: 'amodal' });
+    });
+    it('accepts amodal config with optional jwksUrl + issuer overrides', () => {
+        expect(parseAuthConfig({
+            type: 'amodal',
+            jwksUrl: 'https://example.com/.well-known/jwks.json',
+            issuer: 'custom-issuer',
+        })).toEqual({
+            type: 'amodal',
+            jwksUrl: 'https://example.com/.well-known/jwks.json',
+            issuer: 'custom-issuer',
+        });
+    });
+    it('rejects amodal config with a non-URL jwksUrl', () => {
+        expect(() => parseAuthConfig({ type: 'amodal', jwksUrl: 'not-a-url' })).toThrow(/url/i);
+    });
+    it('rejects unknown type', () => {
+        expect(() => parseAuthConfig({ type: 'wat', whatever: true })).toThrow(/Invalid auth config/);
+    });
+});
+//# sourceMappingURL=config.test.js.map

package/dist/src/auth/config.test.js.map

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

package/dist/src/auth/factory.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Translate a parsed `AuthConfig` into an `AuthStrategy` instance.
+ * The host (cloud's runtime, self-hoster's app) calls this once at boot
+ * with the agent's already-resolved config.
+ */
+import type { AuthConfig } from './config.js';
+import type { AuthStrategy } from './types.js';
+/**
+ * Build an `AuthStrategy` from a validated `AuthConfig`. For `'custom'`
+ * type configs this is async (the user's module is dynamically imported);
+ * everything else resolves synchronously but the function is uniformly
+ * async for ergonomics.
+ */
+export declare function createAuthStrategy(config: AuthConfig): Promise<AuthStrategy>;

package/dist/src/auth/factory.js

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { NoneAuthStrategy } from './strategies/none.js';
+import { HeaderAuthStrategy } from './strategies/header.js';
+import { JwtSecretAuthStrategy } from './strategies/jwt-secret.js';
+import { OidcAuthStrategy } from './strategies/oidc.js';
+import { AmodalAuthStrategy } from './strategies/amodal.js';
+import { loadCustomStrategy } from './strategies/custom-loader.js';
+/**
+ * Build an `AuthStrategy` from a validated `AuthConfig`. For `'custom'`
+ * type configs this is async (the user's module is dynamically imported);
+ * everything else resolves synchronously but the function is uniformly
+ * async for ergonomics.
+ */
+export async function createAuthStrategy(config) {
+    switch (config.type) {
+        case 'none':
+            return new NoneAuthStrategy(config.userId !== undefined ? { userId: config.userId } : {});
+        case 'header':
+            return new HeaderAuthStrategy(config.headerName !== undefined ? { headerName: config.headerName } : {});
+        case 'jwt_secret':
+            return new JwtSecretAuthStrategy({
+                secret: config.secret,
+                ...(config.algorithm ? { algorithm: config.algorithm } : {}),
+                ...(config.issuer ? { issuer: config.issuer } : {}),
+                ...(config.audience ? { audience: config.audience } : {}),
+            });
+        case 'oidc':
+            return new OidcAuthStrategy({
+                issuer: config.issuer,
+                clientId: config.clientId,
+                clientSecret: config.clientSecret,
+                callbackUrl: config.callbackUrl,
+                ...(config.scopes ? { scopes: config.scopes } : {}),
+                sessionSecret: config.sessionSecret,
+                ...(config.cookieName ? { cookieName: config.cookieName } : {}),
+                ...(config.sessionTtlSeconds
+                    ? { sessionTtlSeconds: config.sessionTtlSeconds }
+                    : {}),
+            });
+        case 'custom':
+            return loadCustomStrategy(config.module);
+        case 'amodal':
+            return new AmodalAuthStrategy({
+                ...(config.jwksUrl ? { jwksUrl: config.jwksUrl } : {}),
+                ...(config.issuer ? { issuer: config.issuer } : {}),
+            });
+        default: {
+            const _exhaustive = config;
+            throw new Error(`Unknown auth config type: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=factory.js.map

package/dist/src/auth/factory.js.map

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

package/dist/src/auth/factory.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};

package/dist/src/auth/factory.test.js

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { createAuthStrategy } from './factory.js';
+vi.mock('openid-client', () => ({
+    // OidcAuthStrategy doesn't call discovery() at construction — it
+    // lazy-init's on first request. The factory only needs the module
+    // to import cleanly.
+    discovery: vi.fn(),
+    randomPKCECodeVerifier: vi.fn(),
+    calculatePKCECodeChallenge: vi.fn(),
+    randomState: vi.fn(),
+    buildAuthorizationUrl: vi.fn(),
+    authorizationCodeGrant: vi.fn(),
+}));
+describe('createAuthStrategy', () => {
+    it('returns NoneAuthStrategy for type: none', async () => {
+        const s = await createAuthStrategy({ type: 'none' });
+        expect(s.name).toBe('none');
+    });
+    it('returns HeaderAuthStrategy for type: header', async () => {
+        const s = await createAuthStrategy({ type: 'header' });
+        expect(s.name).toBe('header');
+    });
+    it('returns JwtSecretAuthStrategy for type: jwt_secret', async () => {
+        const s = await createAuthStrategy({ type: 'jwt_secret', secret: 'shh' });
+        expect(s.name).toBe('jwt-secret');
+    });
+    it('returns OidcAuthStrategy for type: oidc', async () => {
+        const s = await createAuthStrategy({
+            type: 'oidc',
+            issuer: 'https://acme.okta.com',
+            clientId: 'abc',
+            clientSecret: 'shh',
+            callbackUrl: 'https://agent.example.com/auth/callback',
+            sessionSecret: 'a-secret-of-at-least-16-chars-long',
+        });
+        expect(s.name).toBe('oidc');
+        expect(s.routes).toBeDefined();
+    });
+    it('returns AmodalAuthStrategy for type: amodal', async () => {
+        const s = await createAuthStrategy({ type: 'amodal' });
+        expect(s.name).toBe('amodal');
+    });
+    it('passes overrides through to AmodalAuthStrategy', async () => {
+        const s = await createAuthStrategy({
+            type: 'amodal',
+            jwksUrl: 'https://example.com/.well-known/jwks.json',
+            issuer: 'custom-issuer',
+        });
+        expect(s.name).toBe('amodal');
+    });
+    it('throws when custom module fails to load', async () => {
+        await expect(createAuthStrategy({ type: 'custom', module: '/nonexistent/path.ts' })).rejects.toThrow(/Failed to load custom auth strategy/);
+    });
+});
+//# sourceMappingURL=factory.test.js.map

package/dist/src/auth/factory.test.js.map

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

package/dist/src/auth/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Pluggable auth — the Warden-shape primitive layer.
+ *
+ *   import {authenticate, JwksAuthStrategy} from '@amodalai/runtime/auth';
+ *
+ *   const platformJwt = new JwksAuthStrategy({jwksUrl: '...'});
+ *   const endUser     = new OidcStrategy({...});
+ *
+ *   // Per-route strategy lists. Studio routes only ever see platformJwt;
+ *   // chat routes accept either platformJwt (Studio testing) OR endUser.
+ *   app.use('/api/files', authenticate(platformJwt));
+ *   app.use('/chat',      authenticate(platformJwt, endUser));
+ *
+ *   // Mount any login-flow routes a strategy registers.
+ *   app.use(authRouter(endUser));
+ *
+ * Single-winner chain semantics: first strategy whose `valid(req)` is
+ * true and `authenticate(req)` returns `'authenticated'` wins. No
+ * merging, no implicit identity overrides.
+ */
+export type { AuthStrategy, AuthResult, AuthSession } from './types.js';
+export { authenticate, authRouter, getSession } from './compose.js';
+export type { AuthLogEvent, AuthenticateOptions } from './compose.js';
+export { JwksAuthStrategy } from './strategies/jwks.js';
+export type { JwksAuthStrategyOptions } from './strategies/jwks.js';
+export { ApiKeyAuthStrategy } from './strategies/api-key.js';
+export type { ApiKeyAuthStrategyOptions, ApiKeyValidationResult, } from './strategies/api-key.js';
+export { HeaderAuthStrategy } from './strategies/header.js';
+export type { HeaderAuthStrategyOptions } from './strategies/header.js';
+export { NoneAuthStrategy } from './strategies/none.js';
+export type { NoneAuthStrategyOptions } from './strategies/none.js';
+export { CookieSessionStrategy } from './strategies/cookie.js';
+export type { CookieSessionStrategyOptions } from './strategies/cookie.js';
+export { JwtSecretAuthStrategy } from './strategies/jwt-secret.js';
+export type { JwtSecretAuthStrategyOptions } from './strategies/jwt-secret.js';
+export { OidcAuthStrategy } from './strategies/oidc.js';
+export type { OidcAuthStrategyOptions } from './strategies/oidc.js';
+export { AmodalAuthStrategy } from './strategies/amodal.js';
+export type { AmodalAuthStrategyOptions } from './strategies/amodal.js';
+export { AuthConfigSchema, parseAuthConfig } from './config.js';
+export type { AuthConfig, NoneAuthConfig, JwtSecretAuthConfig, OidcAuthConfig, HeaderAuthConfig, CustomAuthConfig, AmodalAuthConfig, } from './config.js';
+export { createAuthStrategy } from './factory.js';
+export { loadCustomStrategy } from './strategies/custom-loader.js';

package/dist/src/auth/index.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export { authenticate, authRouter, getSession } from './compose.js';
+export { JwksAuthStrategy } from './strategies/jwks.js';
+export { ApiKeyAuthStrategy } from './strategies/api-key.js';
+export { HeaderAuthStrategy } from './strategies/header.js';
+export { NoneAuthStrategy } from './strategies/none.js';
+export { CookieSessionStrategy } from './strategies/cookie.js';
+export { JwtSecretAuthStrategy } from './strategies/jwt-secret.js';
+export { OidcAuthStrategy } from './strategies/oidc.js';
+export { AmodalAuthStrategy } from './strategies/amodal.js';
+// Config-driven auth — `auth` field in `amodal.json` → AuthStrategy
+export { AuthConfigSchema, parseAuthConfig } from './config.js';
+export { createAuthStrategy } from './factory.js';
+export { loadCustomStrategy } from './strategies/custom-loader.js';
+//# sourceMappingURL=index.js.map

package/dist/src/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwBH,OAAO,EAAC,YAAY,EAAE,UAAU,EAAE,UAAU,EAAC,MAAM,cAAc,CAAC;AAGlE,OAAO,EAAC,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAC,kBAAkB,EAAC,MAAM,yBAAyB,CAAC;AAM3D,OAAO,EAAC,kBAAkB,EAAC,MAAM,wBAAwB,CAAC;AAG1D,OAAO,EAAC,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAC,qBAAqB,EAAC,MAAM,wBAAwB,CAAC;AAG7D,OAAO,EAAC,qBAAqB,EAAC,MAAM,4BAA4B,CAAC;AAGjE,OAAO,EAAC,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAC,kBAAkB,EAAC,MAAM,wBAAwB,CAAC;AAG1D,oEAAoE;AACpE,OAAO,EAAC,gBAAgB,EAAE,eAAe,EAAC,MAAM,aAAa,CAAC;AAU9D,OAAO,EAAC,kBAAkB,EAAC,MAAM,cAAc,CAAC;AAChD,OAAO,EAAC,kBAAkB,EAAC,MAAM,+BAA+B,CAAC"}

package/dist/src/auth/strategies/amodal.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * AmodalAuthStrategy — "Sign in with Amodal."
+ *
+ * The zero-config option for agent owners on the Amodal cloud. End users
+ * sign in with their existing Amodal account; the runtime verifies the
+ * platform-issued JWT against Amodal's JWKS. cf-worker handles the
+ * redirect-to-login dance upstream — by the time a request reaches the
+ * runtime, it carries a valid platform JWT in `Authorization: Bearer`.
+ *
+ * Internally just a `JwksAuthStrategy` preconfigured with Amodal's JWKS
+ * URL and issuer. Self-hosters running their own Amodal-equivalent
+ * platform can override both via constructor options.
+ */
+import type { Request } from 'express';
+import type { AuthResult, AuthStrategy } from '../types.js';
+export interface AmodalAuthStrategyOptions {
+    /**
+     * Override the platform JWKS URL. Defaults to `AMODAL_JWKS_URL` env
+     * var, then to `https://api.amodalai.com/.well-known/jwks.json`.
+     */
+    jwksUrl?: string;
+    /** Override the expected `iss` claim. Defaults to `'aitize-platform'`. */
+    issuer?: string;
+}
+export declare class AmodalAuthStrategy implements AuthStrategy {
+    readonly name = "amodal";
+    private readonly inner;
+    constructor(options?: AmodalAuthStrategyOptions);
+    valid(req: Request): boolean;
+    authenticate(req: Request): Promise<AuthResult>;
+}

package/dist/src/auth/strategies/amodal.js

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { JwksAuthStrategy } from './jwks.js';
+const DEFAULT_AMODAL_JWKS_URL = 'https://api.amodalai.com/.well-known/jwks.json';
+const DEFAULT_AMODAL_ISSUER = 'aitize-platform';
+export class AmodalAuthStrategy {
+    name = 'amodal';
+    inner;
+    constructor(options = {}) {
+        this.inner = new JwksAuthStrategy({
+            jwksUrl: options.jwksUrl ??
+                process.env['AMODAL_JWKS_URL'] ??
+                DEFAULT_AMODAL_JWKS_URL,
+            issuer: options.issuer ?? DEFAULT_AMODAL_ISSUER,
+            authMethod: 'amodal',
+        });
+    }
+    valid(req) {
+        return this.inner.valid(req);
+    }
+    authenticate(req) {
+        return this.inner.authenticate(req);
+    }
+}
+//# sourceMappingURL=amodal.js.map

package/dist/src/auth/strategies/amodal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amodal.js","sourceRoot":"","sources":["../../../../src/auth/strategies/amodal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiBH,OAAO,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAY3C,MAAM,uBAAuB,GAAG,gDAAgD,CAAC;AACjF,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAEhD,MAAM,OAAO,kBAAkB;IACpB,IAAI,GAAG,QAAQ,CAAC;IACR,KAAK,CAAmB;IAEzC,YAAY,UAAqC,EAAE;QACjD,IAAI,CAAC,KAAK,GAAG,IAAI,gBAAgB,CAAC;YAChC,OAAO,EACL,OAAO,CAAC,OAAO;gBACf,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;gBAC9B,uBAAuB;YACzB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,qBAAqB;YAC/C,UAAU,EAAE,QAAQ;SACrB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAY;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,YAAY,CAAC,GAAY;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/src/auth/strategies/api-key.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { Request } from 'express';
+import type { AuthResult, AuthStrategy } from '../types.js';
+export interface ApiKeyValidationResult {
+    /** Required — the principal id this key represents. */
+    userId: string;
+    email?: string;
+    /** Optional — the agent this key is scoped to. */
+    agentId?: string;
+}
+export interface ApiKeyAuthStrategyOptions {
+    /**
+     * Validate the API key. Return `null` for "not a valid key" (chain
+     * rejects with 401). Throw to signal an upstream error (callers can
+     * upgrade these to 502s by wrapping the strategy if desired).
+     */
+    validate: (apiKey: string) => Promise<ApiKeyValidationResult | null>;
+    /** Cache TTL for successful validations (ms). Defaults to 5 minutes. */
+    cacheTtlMs?: number;
+    /** Cap on the LRU cache. Defaults to 10,000 entries. */
+    cacheMaxEntries?: number;
+    /** Token prefix this strategy matches. Defaults to `'ak_'`. */
+    keyPrefix?: string;
+    /** Override `AuthSession.method`. Defaults to `'api-key'`. */
+    authMethod?: string;
+}
+export declare class ApiKeyAuthStrategy implements AuthStrategy {
+    readonly name = "api-key";
+    private readonly validate;
+    private readonly keyPrefix;
+    private readonly authMethod;
+    private readonly cache;
+    constructor(options: ApiKeyAuthStrategyOptions);
+    valid(req: Request): boolean;
+    authenticate(req: Request): Promise<AuthResult>;
+    private buildSession;
+}

package/dist/src/auth/strategies/api-key.js

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * ApiKeyAuthStrategy — `ak_*` Bearer tokens, validated via a caller-
+ * supplied callback (cloud's `/api/me`, a self-hoster's own DB query,
+ * etc.). LRU-cached so repeated requests with the same key skip the
+ * validation round-trip.
+ */
+import { LRUCache } from 'lru-cache';
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_CACHE_MAX = 10_000;
+export class ApiKeyAuthStrategy {
+    name = 'api-key';
+    validate;
+    keyPrefix;
+    authMethod;
+    cache;
+    constructor(options) {
+        this.validate = options.validate;
+        this.keyPrefix = options.keyPrefix ?? 'ak_';
+        this.authMethod = options.authMethod ?? 'api-key';
+        this.cache = new LRUCache({
+            max: options.cacheMaxEntries ?? DEFAULT_CACHE_MAX,
+            ttl: options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS,
+        });
+    }
+    valid(req) {
+        const auth = req.headers['authorization'];
+        if (typeof auth !== 'string' || !auth.startsWith('Bearer '))
+            return false;
+        const token = auth.slice(7);
+        return token.startsWith(this.keyPrefix);
+    }
+    async authenticate(req) {
+        const auth = req.headers['authorization'];
+        if (typeof auth !== 'string')
+            return { kind: 'rejected', reason: 'No bearer token' };
+        const token = auth.slice(7);
+        const cached = this.cache.get(token);
+        if (cached) {
+            return { kind: 'authenticated', session: this.buildSession(cached) };
+        }
+        const result = await this.validate(token);
+        if (!result)
+            return { kind: 'rejected', reason: 'Invalid API key' };
+        this.cache.set(token, result);
+        return { kind: 'authenticated', session: this.buildSession(result) };
+    }
+    buildSession(result) {
+        return {
+            user: {
+                id: result.userId,
+                ...(result.email ? { email: result.email } : {}),
+            },
+            method: this.authMethod,
+            ...(result.agentId ? { agentId: result.agentId } : {}),
+        };
+    }
+}
+//# sourceMappingURL=api-key.js.map

package/dist/src/auth/strategies/api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.js","sourceRoot":"","sources":["../../../../src/auth/strategies/api-key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,OAAO,EAAC,QAAQ,EAAC,MAAM,WAAW,CAAC;AA6BnC,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAC3C,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEjC,MAAM,OAAO,kBAAkB;IACpB,IAAI,GAAG,SAAS,CAAC;IACT,QAAQ,CAAwC;IAChD,SAAS,CAAS;IAClB,UAAU,CAAS;IACnB,KAAK,CAA2C;IAEjE,YAAY,OAAkC;QAC5C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;QAC5C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,SAAS,CAAC;QAClD,IAAI,CAAC,KAAK,GAAG,IAAI,QAAQ,CAAiC;YACxD,GAAG,EAAE,OAAO,CAAC,eAAe,IAAI,iBAAiB;YACjD,GAAG,EAAE,OAAO,CAAC,UAAU,IAAI,oBAAoB;SAChD,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAY;QAChB,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,KAAK,CAAC;QAC1E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,GAAY;QAC7B,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,EAAC,CAAC;QACnF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAE5B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,EAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAC,CAAC;QACrE,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM;YAAE,OAAO,EAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,EAAC,CAAC;QAClE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC9B,OAAO,EAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAC,CAAC;IACrE,CAAC;IAEO,YAAY,CAAC,MAA8B;QACjD,OAAO;YACL,IAAI,EAAE;gBACJ,EAAE,EAAE,MAAM,CAAC,MAAM;gBACjB,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAC,KAAK,EAAE,MAAM,CAAC,KAAK,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/C;YACD,MAAM,EAAE,IAAI,CAAC,UAAU;YACvB,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAC,OAAO,EAAE,MAAM,CAAC,OAAO,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACrD,CAAC;IACJ,CAAC;CACF"}

package/dist/src/auth/strategies/auth-modes.integration.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};