@oxy.so/contracts 1.0.0

package/dist/cjs/agency.js

@@ -0,0 +1,439 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizedAppEventSchema = exports.catalogRegistrationSchema = exports.appCapabilityCatalogSchema = exports.catalogEventSchema = exports.catalogToolSchema = exports.auditEventSchema = exports.auditResultSchema = exports.policyDecisionSchema = exports.capabilityTicketClaimsSchema = exports.automationDefinitionSchema = exports.automationDataFlowSchema = exports.automationActorSelectionSchema = exports.automationTriggerSchema = exports.delegationGrantSchema = exports.capabilityCoordinatorSchema = exports.executionAuthorizationRefSchema = exports.grantLimitSchema = exports.toolGrantOverrideSchema = exports.resourceRefSchema = exports.actorRefSchema = exports.capabilityPackageSchema = exports.CAPABILITY_PACKAGES = exports.autonomyLevelSchema = exports.AUTONOMY_LEVELS = void 0;
+const zod_1 = require("zod");
+const nonEmptyStringSchema = zod_1.z.string().trim().min(1);
+const identifierSchema = zod_1.z.string().trim().min(1).max(255);
+const limitKeySchema = zod_1.z.string().regex(/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$/, 'limit keys must be dot-separated input property names').max(255);
+const auditCodeSchema = zod_1.z.string().regex(/^[A-Za-z0-9_.:-]{1,128}$/);
+const sha256HexSchema = zod_1.z.string().regex(/^[a-f0-9]{64}$/);
+const invocationPathSchema = zod_1.z.string().regex(/^\/(?!\/)[^\\?#]*$/, 'invocation paths must be absolute app-local paths without backslashes, query or fragment');
+/** Autonomy is ordered from least to most permissive. */
+exports.AUTONOMY_LEVELS = [
+    'read_only',
+    'draft',
+    'execute_on_request',
+    'autonomous',
+];
+exports.autonomyLevelSchema = zod_1.z.enum(exports.AUTONOMY_LEVELS);
+exports.CAPABILITY_PACKAGES = [
+    'read',
+    'create',
+    'publish',
+    'communicate',
+    'administer',
+    'finance',
+    'security',
+    'delegate',
+];
+exports.capabilityPackageSchema = zod_1.z.enum(exports.CAPABILITY_PACKAGES);
+exports.actorRefSchema = zod_1.z.discriminatedUnion('type', [
+    zod_1.z.object({
+        type: zod_1.z.literal('alia'),
+        ownerAccountId: identifierSchema,
+    }).strict(),
+    zod_1.z.object({
+        type: zod_1.z.literal('agent'),
+        accountId: identifierSchema,
+    }).strict(),
+]);
+exports.resourceRefSchema = zod_1.z.object({
+    appId: identifierSchema,
+    effectiveAccountId: identifierSchema,
+    resourceType: identifierSchema,
+    resourceId: identifierSchema,
+}).strict();
+exports.toolGrantOverrideSchema = zod_1.z.object({
+    tool: identifierSchema,
+    decision: zod_1.z.enum(['allow', 'deny']),
+}).strict();
+exports.grantLimitSchema = zod_1.z.object({
+    tool: identifierSchema,
+    key: limitKeySchema,
+    // Persisted limits are deliberately closed scalar bounds. Strings and
+    // arrays are tool arguments in disguise (recipient lists, prompts, search
+    // queries) and ADR 0016 forbids persisting those in Oxy.
+    value: zod_1.z.union([zod_1.z.number().finite(), zod_1.z.boolean()]),
+}).strict();
+exports.executionAuthorizationRefSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z.object({
+        kind: zod_1.z.literal('direct_request'),
+        id: identifierSchema,
+    }).strict(),
+    zod_1.z.object({
+        kind: zod_1.z.literal('automation'),
+        id: identifierSchema,
+        automationId: identifierSchema,
+    }).strict(),
+]);
+exports.capabilityCoordinatorSchema = zod_1.z.object({
+    applicationId: identifierSchema,
+    credentialId: identifierSchema,
+}).strict();
+exports.delegationGrantSchema = zod_1.z.object({
+    id: identifierSchema,
+    ownerAccountId: identifierSchema,
+    actor: exports.actorRefSchema,
+    resource: exports.resourceRefSchema,
+    capabilityPackages: zod_1.z.array(exports.capabilityPackageSchema),
+    capabilities: zod_1.z.array(identifierSchema),
+    toolOverrides: zod_1.z.array(exports.toolGrantOverrideSchema).default([]),
+    limits: zod_1.z.array(exports.grantLimitSchema).default([]),
+    maximumAutonomy: exports.autonomyLevelSchema,
+    canRedelegate: zod_1.z.boolean().default(false),
+    expiresAt: zod_1.z.string().datetime().nullable(),
+    revokedAt: zod_1.z.string().datetime().nullable().default(null),
+    createdAt: zod_1.z.string().datetime(),
+    updatedAt: zod_1.z.string().datetime(),
+}).strict();
+exports.automationTriggerSchema = zod_1.z.discriminatedUnion('type', [
+    zod_1.z.object({ type: zod_1.z.literal('manual') }).strict(),
+    zod_1.z.object({
+        type: zod_1.z.literal('event'),
+        appId: identifierSchema,
+        eventType: identifierSchema,
+        resource: exports.resourceRefSchema.optional(),
+    }).strict(),
+    zod_1.z.object({
+        type: zod_1.z.literal('schedule'),
+        cron: nonEmptyStringSchema,
+        timezone: nonEmptyStringSchema,
+    }).strict(),
+]);
+exports.automationActorSelectionSchema = zod_1.z.discriminatedUnion('mode', [
+    zod_1.z.object({ mode: zod_1.z.literal('fixed'), actor: exports.actorRefSchema }).strict(),
+    zod_1.z.object({ mode: zod_1.z.literal('automatic') }).strict(),
+]);
+exports.automationDataFlowSchema = zod_1.z.object({
+    sources: zod_1.z.array(exports.resourceRefSchema),
+    destinations: zod_1.z.array(exports.resourceRefSchema),
+}).strict();
+exports.automationDefinitionSchema = zod_1.z.object({
+    id: identifierSchema,
+    ownerAccountId: identifierSchema,
+    objective: nonEmptyStringSchema,
+    trigger: exports.automationTriggerSchema,
+    actorSelection: exports.automationActorSelectionSchema,
+    inputs: zod_1.z.record(zod_1.z.unknown()),
+    resources: zod_1.z.array(exports.resourceRefSchema),
+    dataFlow: exports.automationDataFlowSchema,
+    maximumAutonomy: exports.autonomyLevelSchema,
+    limits: zod_1.z.array(exports.grantLimitSchema).default([]),
+    enabled: zod_1.z.boolean(),
+    createdAt: zod_1.z.string().datetime(),
+    updatedAt: zod_1.z.string().datetime(),
+}).strict();
+exports.capabilityTicketClaimsSchema = zod_1.z.object({
+    iss: nonEmptyStringSchema,
+    aud: identifierSchema,
+    sub: identifierSchema,
+    jti: identifierSchema,
+    iat: zod_1.z.number().int().nonnegative(),
+    exp: zod_1.z.number().int().positive(),
+    runId: identifierSchema,
+    stepId: identifierSchema.optional(),
+    automationId: identifierSchema.optional(),
+    executionAuthorization: exports.executionAuthorizationRefSchema,
+    coordinator: exports.capabilityCoordinatorSchema,
+    grantId: identifierSchema.optional(),
+    requesterAccountId: identifierSchema,
+    ownerAccountId: identifierSchema,
+    actor: exports.actorRefSchema,
+    resource: exports.resourceRefSchema,
+    tool: identifierSchema,
+    capabilities: zod_1.z.array(identifierSchema).min(1),
+    limits: zod_1.z.array(exports.grantLimitSchema).default([]),
+    autonomy: exports.autonomyLevelSchema,
+}).strict().superRefine((claims, context) => {
+    const expectedSubject = claims.actor.type === 'agent'
+        ? claims.actor.accountId
+        : `alia:${claims.actor.ownerAccountId}`;
+    if (claims.sub !== expectedSubject) {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'sub must identify the exact executing actor',
+            path: ['sub'],
+        });
+    }
+    if (claims.actor.type === 'alia' && claims.actor.ownerAccountId !== claims.ownerAccountId) {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'Alia actor owner must match ownerAccountId',
+            path: ['actor', 'ownerAccountId'],
+        });
+    }
+    if (claims.exp <= claims.iat) {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'exp must be later than iat',
+            path: ['exp'],
+        });
+    }
+    if (claims.executionAuthorization.kind === 'automation') {
+        if (claims.automationId !== claims.executionAuthorization.automationId) {
+            context.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'automationId must match the execution authorization',
+                path: ['automationId'],
+            });
+        }
+    }
+    else if (claims.automationId !== undefined || claims.autonomy === 'autonomous') {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'direct requests cannot carry automation identity or autonomous authority',
+            path: ['executionAuthorization'],
+        });
+    }
+    for (const [index, limit] of claims.limits.entries()) {
+        if (limit.tool !== claims.tool) {
+            context.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'ticket limits must be scoped to the ticket tool',
+                path: ['limits', index, 'tool'],
+            });
+        }
+    }
+});
+exports.policyDecisionSchema = zod_1.z.object({
+    allowed: zod_1.z.boolean(),
+    reason: identifierSchema,
+    effectiveAutonomy: exports.autonomyLevelSchema.optional(),
+    grantId: identifierSchema.optional(),
+}).strict();
+exports.auditResultSchema = zod_1.z.object({
+    status: zod_1.z.enum(['planned', 'allowed', 'denied', 'succeeded', 'failed', 'rolled_back']),
+    code: auditCodeSchema.optional(),
+}).strict();
+exports.auditEventSchema = zod_1.z.object({
+    eventId: identifierSchema,
+    occurredAt: zod_1.z.string().datetime(),
+    requesterAccountId: identifierSchema,
+    coordinator: exports.capabilityCoordinatorSchema,
+    executor: exports.actorRefSchema,
+    effectiveAccountId: identifierSchema,
+    resource: exports.resourceRefSchema,
+    appId: identifierSchema,
+    tool: identifierSchema,
+    capabilities: zod_1.z.array(identifierSchema),
+    policyDecision: exports.policyDecisionSchema,
+    result: exports.auditResultSchema,
+    rollback: zod_1.z.object({
+        supported: zod_1.z.boolean(),
+        attempted: zod_1.z.boolean(),
+        succeeded: zod_1.z.boolean().optional(),
+    }).strict(),
+    correlation: zod_1.z.object({
+        runId: identifierSchema,
+        stepId: identifierSchema.optional(),
+        automationId: identifierSchema.optional(),
+        idempotencyKeyHash: sha256HexSchema.optional(),
+        capabilityTicketId: identifierSchema.optional(),
+    }).strict(),
+}).strict();
+exports.catalogToolSchema = zod_1.z.object({
+    name: identifierSchema,
+    version: identifierSchema,
+    description: nonEmptyStringSchema,
+    inputSchema: zod_1.z.record(zod_1.z.unknown()),
+    outputSchema: zod_1.z.record(zod_1.z.unknown()).optional(),
+    capabilityPackage: exports.capabilityPackageSchema,
+    requiredCapabilities: zod_1.z.array(identifierSchema).min(1),
+    resourceTypes: zod_1.z.array(identifierSchema).min(1),
+    effect: zod_1.z.enum(['read', 'write', 'external', 'financial', 'security']),
+    idempotency: zod_1.z.enum(['none', 'supported', 'required']),
+    rollback: zod_1.z.enum(['none', 'manual', 'supported']),
+    exposure: zod_1.z.array(zod_1.z.enum(['internal', 'mcp'])).min(1),
+    limitKeys: zod_1.z.array(zod_1.z.object({
+        key: limitKeySchema,
+        kind: zod_1.z.enum(['maximum_number', 'exact_boolean']),
+    }).strict()).default([]),
+    invocation: zod_1.z.object({
+        method: zod_1.z.enum(['GET', 'POST', 'PATCH', 'PUT', 'DELETE']),
+        path: invocationPathSchema,
+    }).strict(),
+}).strict().superRefine((tool, context) => {
+    const requireUnique = (values, path) => {
+        if (new Set(values).size !== values.length) {
+            context.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: `${path} must not contain duplicates`,
+                path: [path],
+            });
+        }
+    };
+    requireUnique(tool.requiredCapabilities, 'requiredCapabilities');
+    requireUnique(tool.resourceTypes, 'resourceTypes');
+    requireUnique(tool.exposure, 'exposure');
+    requireUnique(tool.limitKeys.map((limit) => limit.key), 'limitKeys');
+    const inputSchemaAt = (key) => {
+        let schema = tool.inputSchema;
+        for (const segment of key.split('.')) {
+            if (typeof schema !== 'object' || schema === null || Array.isArray(schema))
+                return null;
+            const properties = schema.properties;
+            if (typeof properties !== 'object' || properties === null || Array.isArray(properties))
+                return null;
+            schema = properties[segment];
+        }
+        return typeof schema === 'object' && schema !== null && !Array.isArray(schema)
+            ? schema
+            : null;
+    };
+    for (const [index, limit] of tool.limitKeys.entries()) {
+        const input = inputSchemaAt(limit.key);
+        const inputType = input?.type;
+        const compatible = limit.kind === 'maximum_number'
+            ? inputType === 'number' || inputType === 'integer'
+            : inputType === 'boolean';
+        if (!compatible) {
+            context.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: `${limit.kind} must name a compatible input property`,
+                path: ['limitKeys', index, 'key'],
+            });
+        }
+    }
+    if (tool.inputSchema.type !== 'object') {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'MCP-compatible tool input schemas must have object roots',
+            path: ['inputSchema', 'type'],
+        });
+    }
+    if (tool.outputSchema && tool.outputSchema.type !== 'object') {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'Tool output schemas must have object roots',
+            path: ['outputSchema', 'type'],
+        });
+    }
+    if (tool.effect !== 'read' && tool.idempotency === 'none') {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'Effectful tools must declare idempotency support',
+            path: ['idempotency'],
+        });
+    }
+    if (tool.effect === 'financial' && tool.capabilityPackage !== 'finance') {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'Financial effects require the finance capability package',
+            path: ['capabilityPackage'],
+        });
+    }
+    if (tool.effect === 'security' && tool.capabilityPackage !== 'security') {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'Security effects require the security capability package',
+            path: ['capabilityPackage'],
+        });
+    }
+    if ((tool.effect === 'financial' || tool.effect === 'security') && tool.idempotency !== 'required') {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'Financial and security effects require idempotency keys',
+            path: ['idempotency'],
+        });
+    }
+    if (tool.effect !== 'read' && tool.invocation.method === 'GET') {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'Effectful tools cannot use GET invocations',
+            path: ['invocation', 'method'],
+        });
+    }
+});
+exports.catalogEventSchema = zod_1.z.object({
+    type: identifierSchema,
+    version: identifierSchema,
+    description: nonEmptyStringSchema,
+    dataSchema: zod_1.z.record(zod_1.z.unknown()),
+    resourceTypes: zod_1.z.array(identifierSchema).min(1),
+}).strict();
+exports.appCapabilityCatalogSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal('1'),
+    appId: identifierSchema,
+    version: identifierSchema,
+    audience: identifierSchema,
+    /** HTTPS origin that serves the catalog's internal invocation paths. */
+    internalBaseUrl: zod_1.z.string().url().superRefine((value, context) => {
+        const url = new URL(value);
+        const localDevelopment = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+        if (url.protocol !== 'https:' && !(localDevelopment && url.protocol === 'http:')) {
+            context.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'internalBaseUrl must use HTTPS outside local development',
+            });
+        }
+        if (url.pathname !== '/' || url.search !== '' || url.hash !== '') {
+            context.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'internalBaseUrl must be an origin without path, query or fragment',
+            });
+        }
+    }),
+    /** Account-scoped resource used for native Alia bindings without app-specific code. */
+    accountResourceType: identifierSchema,
+    /** Canonical protected-resource URI when this catalog is also exposed as an external MCP server. */
+    externalMcp: zod_1.z.object({
+        resource: zod_1.z.string().url().superRefine((value, context) => {
+            const url = new URL(value);
+            const localDevelopment = url.hostname === 'localhost'
+                || url.hostname === '127.0.0.1'
+                || url.hostname === '[::1]';
+            if (url.protocol !== 'https:' && !(localDevelopment && url.protocol === 'http:')) {
+                context.addIssue({
+                    code: zod_1.z.ZodIssueCode.custom,
+                    message: 'externalMcp.resource must use HTTPS outside local development',
+                });
+            }
+            if (url.username || url.password || url.search || url.hash) {
+                context.addIssue({
+                    code: zod_1.z.ZodIssueCode.custom,
+                    message: 'externalMcp.resource cannot contain credentials, query or fragment',
+                });
+            }
+        }),
+    }).strict().optional(),
+    tools: zod_1.z.array(exports.catalogToolSchema),
+    events: zod_1.z.array(exports.catalogEventSchema),
+}).strict().superRefine((catalog, context) => {
+    const names = new Set();
+    for (const [index, tool] of catalog.tools.entries()) {
+        if (names.has(tool.name)) {
+            context.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: `Duplicate tool name: ${tool.name}`,
+                path: ['tools', index, 'name'],
+            });
+        }
+        names.add(tool.name);
+    }
+    const eventTypes = new Set();
+    for (const [index, event] of catalog.events.entries()) {
+        if (eventTypes.has(event.type)) {
+            context.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: `Duplicate event type: ${event.type}`,
+                path: ['events', index, 'type'],
+            });
+        }
+        eventTypes.add(event.type);
+    }
+});
+exports.catalogRegistrationSchema = zod_1.z.object({
+    catalog: exports.appCapabilityCatalogSchema,
+    digest: zod_1.z.string().regex(/^[a-f0-9]{64}$/),
+    signature: nonEmptyStringSchema,
+    deployedAt: zod_1.z.string().datetime(),
+}).strict();
+exports.normalizedAppEventSchema = zod_1.z.object({
+    eventId: identifierSchema,
+    appId: identifierSchema,
+    accountId: identifierSchema,
+    resource: exports.resourceRefSchema,
+    type: identifierSchema,
+    occurredAt: zod_1.z.string().datetime(),
+    data: zod_1.z.record(zod_1.z.unknown()),
+}).strict();

package/dist/cjs/browserHub.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hubAuthorizeResultSchema = exports.hubAuthorizeRequestSchema = exports.hubActivateRequestSchema = exports.hubClaimRequestSchema = exports.hubSessionSchema = exports.browserHubRevokeResponseSchema = exports.browserHubErrorSchema = exports.browserHubResolveResponseSchema = exports.browserHubHandleResponseSchema = exports.browserHubHandleRequestSchema = exports.browserHubHandleSchema = exports.BROWSER_HUB_HANDLE_TTL_MS = exports.BROWSER_HUB_COOKIE_ATTRIBUTES = exports.BROWSER_HUB_COOKIE_NAME = void 0;
+const zod_1 = require("zod");
+const deviceDirectory_1 = require("./deviceDirectory");
+/**
+ * The browser DeviceSession hub at `auth.oxy.so` (issue #937, Phase 5, ADR 0003).
+ *
+ * Two wire surfaces live in this file and they are deliberately different
+ * shapes, because they answer to different callers:
+ *
+ *  - The `browserHub*` schemas below the first divider are the API's
+ *    (`api.oxy.so/session/browser-hub/*`), spoken ONLY by the IdP's own
+ *    server/edge layer. They carry the raw handle and a bearer, so nothing that
+ *    speaks them may run in a browser.
+ *  - The `hub*` schemas below the second divider are the EDGE's
+ *    (`auth.oxy.so/hub/*`), spoken by the IdP SPA. They carry neither: the
+ *    handle stays in an `HttpOnly` cookie the script cannot read, and the
+ *    device-wide bearer stays at the edge.
+ *
+ * That split is the whole point of the phase. A single schema covering both
+ * would let a refactor move a credential across the boundary without any type
+ * changing shape.
+ *
+ * ## What is NOT reopened here
+ *
+ * Relying-party origins remain zero-cookie: they keep `{deviceId,
+ * deviceSecret}` + `POST /session/device/token` and set no cookie of any kind.
+ * `auth.oxy.so` alone holds a handle, first-party only. There is no
+ * refresh-token family and no bootstrap hop.
+ */
+/* -------------------------------------------------------------------------- */
+/*  The cookie                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * The one cookie name, `__Host-` prefixed.
+ *
+ * The prefix is not decoration: a browser refuses to store a `__Host-` cookie
+ * that carries a `Domain` attribute or a `Path` other than `/`, or that arrives
+ * without `Secure`. So the name itself is what makes "bound to `auth.oxy.so`
+ * alone, readable by no other `oxy.so` host" enforced by the client rather than
+ * merely intended by the server — including against a compromised sibling
+ * subdomain, which is the specific attack `Domain=.oxy.so` would have opened.
+ */
+exports.BROWSER_HUB_COOKIE_NAME = '__Host-oxy-device';
+/**
+ * The exact attribute set the edge sets, in the order it writes them.
+ *
+ * Held as data rather than as a template string so a test can assert the set
+ * rather than a rendered line, and so removing one attribute is a diff to a
+ * named constant instead of an edit inside a string literal.
+ *
+ * `Max-Age` is deliberately NOT in this list — see
+ * {@link BROWSER_HUB_HANDLE_TTL_MS}, which the edge appends. Everything here is
+ * a SECURITY attribute and none of them is ever conditional.
+ */
+exports.BROWSER_HUB_COOKIE_ATTRIBUTES = ['Secure', 'HttpOnly', 'SameSite=Lax', 'Path=/'];
+/**
+ * How long a hub handle lives, server-side and in the cookie alike.
+ *
+ * Thirty days. The cookie's `Max-Age` is derived from this same constant so the
+ * two cannot disagree: a cookie outliving its credential produces a browser that
+ * believes it is signed in and is refused on every call, and a credential
+ * outliving its cookie leaves an un-addressable row alive on the server.
+ *
+ * A hub handle is NOT a session cookie (one with no `Max-Age`, discarded when
+ * the browser closes). It cannot be: the thing it identifies is the browser
+ * PROFILE's device session, and a device session that evaporates when the user
+ * quits their browser would send them back to a QR scan every morning — the
+ * exact failure ADR 0003 exists to remove.
+ */
+exports.BROWSER_HUB_HANDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/* -------------------------------------------------------------------------- */
+/*  api.oxy.so/session/browser-hub/*  —  spoken by the edge, never a browser   */
+/* -------------------------------------------------------------------------- */
+/**
+ * The raw handle, as it travels between the edge and the API.
+ *
+ * An opaque base64url random value and NOTHING else — no token, no user id, no
+ * device id, no account id, no serialized state. The server stores only
+ * `sha256(handle)`, so a dump of the column cannot address a browser.
+ *
+ * The minimum length is a floor against an empty or truncated value reaching a
+ * hash comparison, not a statement about the entropy: that is fixed by the
+ * issuer (`BROWSER_HUB_HANDLE_BYTES` in the API), and a handle is the only
+ * credential in this flow, so it is 256 bits.
+ */
+exports.browserHubHandleSchema = zod_1.z.string().min(32);
+/** Request body of every handle-presenting API endpoint. */
+exports.browserHubHandleRequestSchema = zod_1.z.object({
+    handle: exports.browserHubHandleSchema,
+});
+/**
+ * Response of `POST /session/browser-hub/establish` and `.../rotate`.
+ *
+ * The raw handle is returned exactly ONCE, to the edge, which puts it straight
+ * into the cookie and keeps no copy. It is never logged, never re-readable, and
+ * never reaches the browser's script context.
+ */
+exports.browserHubHandleResponseSchema = zod_1.z.object({
+    handle: exports.browserHubHandleSchema,
+    expiresAt: zod_1.z.string(),
+});
+/**
+ * Response of `POST /session/browser-hub/resolve` — the browser's device
+ * session, resolved from the handle alone.
+ *
+ * Carries a bearer because the edge needs one to run the authorize lane on the
+ * browser's behalf. It is the ordinary short-lived access token of the device's
+ * active context, and it stops at the edge.
+ */
+exports.browserHubResolveResponseSchema = zod_1.z.object({
+    accessToken: zod_1.z.string().min(1),
+    expiresAt: zod_1.z.string(),
+    directory: deviceDirectory_1.deviceDirectorySchema,
+});
+/**
+ * Why a handle did not resolve. A CLOSED set, and deliberately coarse.
+ *
+ *  - `invalid_handle`    — unknown, expired, or revoked. One code for all
+ *                          three: distinguishing them would tell a caller
+ *                          holding a guessed value whether it ever existed.
+ *  - `no_active_session` — the handle is good and the device has nothing live
+ *                          to mint for. The credential is NOT revoked; the
+ *                          browser re-authenticates and keeps its cookie.
+ */
+exports.browserHubErrorSchema = zod_1.z.enum(['invalid_handle', 'no_active_session']);
+/** Response of `POST /session/browser-hub/revoke`. Idempotent by construction. */
+exports.browserHubRevokeResponseSchema = zod_1.z.object({
+    revoked: zod_1.z.boolean(),
+});
+/* -------------------------------------------------------------------------- */
+/*  auth.oxy.so/hub/*  —  spoken by the IdP SPA                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * What the SPA is allowed to know about the hub session.
+ *
+ * `signed_out` covers "no cookie", "cookie present but the handle no longer
+ * resolves" and "resolved, but the device has nothing live" — from the script's
+ * side those are one state, and collapsing them here is what stops a UI from
+ * branching on a distinction it must not act on.
+ *
+ * `active` carries the DIRECTORY and no credential. A switcher renders from it;
+ * nothing in it can be spent against the API. The bearer that produced it never
+ * left the edge.
+ */
+exports.hubSessionSchema = zod_1.z.discriminatedUnion('status', [
+    zod_1.z.object({ status: zod_1.z.literal('signed_out') }),
+    zod_1.z.object({ status: zod_1.z.literal('active'), directory: deviceDirectory_1.deviceDirectorySchema }),
+]);
+/** Request body of `POST /hub/claim` — the Commons approval lane's handoff. */
+exports.hubClaimRequestSchema = zod_1.z.object({
+    /**
+     * The secret `sessionToken` of an approved `AuthSession`, held only by the
+     * page that created it. The edge spends it server-side: the access token and
+     * device secret the claim yields are consumed to establish the hub and are
+     * then discarded, so neither is ever returned to the script.
+     */
+    sessionToken: zod_1.z.string().min(1),
+});
+/** Request body of `POST /hub/activate` — pick the globally active context. */
+exports.hubActivateRequestSchema = zod_1.z.object({
+    contextId: zod_1.z.string().min(1),
+});
+/**
+ * Request body of `POST /hub/authorize` — a later official origin joining.
+ *
+ * There is no `prompt` field, and that is not an omission. `'none'` is absent
+ * from `buildOAuthAuthorizeUrl`'s union in `@oxy.so/core` precisely so a silent
+ * loop cannot be rebuilt in one line, and this endpoint would be the second
+ * place to rebuild it. A caller that needs a login or consent prompt gets one
+ * by not passing `approve`.
+ */
+exports.hubAuthorizeRequestSchema = zod_1.z.object({
+    clientId: zod_1.z.string().min(1),
+    redirectUri: zod_1.z.string().url(),
+    state: zod_1.z.string().optional(),
+    codeChallenge: zod_1.z.string().min(1),
+    /** S256 only. `plain` is refused before the request leaves the edge. */
+    codeChallengeMethod: zod_1.z.literal('S256'),
+    scope: zod_1.z.string().optional(),
+    /**
+     * The user's explicit answer on the consent screen.
+     *
+     * Absent or `false` means "tell me whether consent is needed"; the edge then
+     * returns `consent_required` and mints nothing. Only `true` may mint, and only
+     * the consent screen's own button sends it — which is why the decision of
+     * WHETHER consent is required is re-read from the server on both passes rather
+     * than remembered from the first.
+     */
+    approve: zod_1.z.boolean().optional(),
+});
+/**
+ * Result of `POST /hub/authorize`.
+ *
+ * `signed_out` is the honest answer for a browser with no hub session: the SPA
+ * runs the ordinary Commons-first authentication and tries again. It is never a
+ * redirect the edge performs on the browser's behalf — no automatic chain
+ * across Oxy origins, and nothing here can be hidden inside an iframe.
+ */
+exports.hubAuthorizeResultSchema = zod_1.z.discriminatedUnion('status', [
+    zod_1.z.object({ status: zod_1.z.literal('signed_out') }),
+    zod_1.z.object({
+        status: zod_1.z.literal('consent_required'),
+        reason: zod_1.z.enum(['new', 'scope_changed']),
+        userConsentScopes: zod_1.z.array(zod_1.z.string()).optional(),
+    }),
+    zod_1.z.object({
+        status: zod_1.z.literal('code'),
+        code: zod_1.z.string().min(1),
+        state: zod_1.z.string().nullable(),
+        redirectUri: zod_1.z.string(),
+        expiresIn: zod_1.z.number().int().positive(),
+    }),
+]);