@substrat-run/contracts 0.153.0 → 0.154.0

package/dist/reserved-keys.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Keys no person may hold (#2425, #2430): the one reading of `holder: 'system'` on a manifest's
+ * permission declaration, applied wherever a permission surface is judged. `lint:permissions`
+ * (`tools/reserved-keys.mts`), `buildPermissionRegistry` and so `substrat push`, the push boundary
+ * (`pushedPermissionRegistry`), and a scope host's role doors (the kernel's `reservedRoleRefusal`)
+ * all call these, so none of them can read the mark differently.
+ *
+ * A vertical's person-facing surface is its `ROLES` and its `ENTITY_GRANTS` shapes (what a
+ * principal is handed per entity). A module's SYSTEM principal is a different declaration:
+ * `manifest.schedules[].permissions` (`system:<module>`) and `manifest.peers[].permissions`
+ * (`vertical:<slug>`). So "a system-only key" needs no new concept in the surface: it may appear
+ * in the second place and never in the first. The one role that may carry one is a role declared
+ * `holder: 'system'` (K-55), and it may carry nothing else.
+ *
+ * This is NOT the purge-only notion of K-45 (`entity-trash.ts`): that scopes a key a system
+ * principal already holds to one schedule's call. It says where a system principal may USE a key,
+ * not that a person may not be given it.
+ *
+ * Pure and dependency-free, so `tools/` can load it from source.
+ */
+/** What the manifests say about a key reserved to a system principal. */
+export interface ReservedKey {
+    description: string;
+    /** Every module that declares the key `holder: 'system'`, sorted. */
+    declaredBy: string[];
+}
+/** The part of a module a reservation is read from: its manifest's id and permission declarations. */
+export interface ReservedKeySource {
+    manifest: {
+        id: string;
+        permissions: readonly {
+            key: string;
+            description: string;
+            holder?: 'system';
+        }[];
+        /** What a fresh install's owner is granted on day one: a person's grant (#2430). */
+        ownerGrants?: readonly string[];
+    };
+}
+/**
+ * Every key a manifest declares `holder: 'system'`.
+ *
+ * A union, not a vote: one module declaring the key reserved reserves it, whatever another module
+ * declaring the same key says. Otherwise a vertical could lift an engine's reservation by
+ * re-declaring the key, unmarked, in a module of its own.
+ */
+export declare function reservedKeysOf(modules: readonly ReservedKeySource[]): Map<string, ReservedKey>;
+export interface ReservedKeyOffence {
+    /**
+     * Where it was granted: `role <key>`, `system-held role <key>`, `grant shape on <entityType>`, or
+     * a person grant's own name (`owner grants of <module>`, `owner grants (substrat.ownerGrants)`).
+     */
+    where: string;
+    key: string;
+    /** Set for a system-held role holding a key that is not reserved to a system principal. */
+    notReserved?: true;
+    /** Set for a system-held role that holds no reserved key at all. */
+    empty?: true;
+}
+/** The surface a reservation is judged against: the roles, the entity grant shapes, and person grants. */
+export interface ReservedKeySurface {
+    roles: readonly {
+        key: string;
+        permissions: readonly string[];
+        holder?: 'person' | 'system';
+    }[];
+    grants: readonly {
+        entityType: string;
+        permissions: readonly string[];
+    }[];
+    /** #2430: keys a person is granted directly, each set named as the refusal names it (`ownerGrantSets`). */
+    personGrants?: readonly {
+        where: string;
+        permissions: readonly string[];
+    }[];
+}
+/**
+ * #2430: the owner grants a vertical declares, as named person grants — each module manifest's
+ * `ownerGrants` and, when given, the deployment's own `substrat.ownerGrants` (package.json). An
+ * install grants them to its owner, a person, so a reserved key among them is a person's grant.
+ */
+export declare function ownerGrantSets(modules: readonly ReservedKeySource[], deployment?: readonly string[]): {
+    where: string;
+    permissions: readonly string[];
+}[];
+/**
+ * #2430: package.json `substrat.ownerGrants` as the owner-grant list `ownerGrantSets` takes, or why
+ * it is not one. Absent is no owner grant; anything but an array of keys is a broken declaration,
+ * refused rather than read as none, since what it means to grant is exactly what cannot be judged.
+ */
+export declare function declaredOwnerGrants(value: unknown): {
+    grants: string[];
+} | {
+    problem: string;
+};
+/** Every person-facing grant of a reserved key, and every malformed system-held role, in surface order. */
+export declare function reservedKeyOffences(surface: ReservedKeySurface, reserved: {
+    has(key: string): boolean;
+}): ReservedKeyOffence[];
+/**
+ * One offence on one line: where, which key, and why it is refused. `reserved` names the module
+ * that marks the key; without it (the push boundary, which has only the registry's rows, whose
+ * `declaredBy` lists every declarer, marked or not) the line attributes the mark to nobody.
+ */
+export declare function reservedKeyLine(o: ReservedKeyOffence, reserved?: ReadonlyMap<string, ReservedKey>): string;
+/** The refusal's text, naming the vertical, the file, each grant, who reserved the key and the remedy. */
+export declare function reservedKeyMessage(rel: string, entry: string, offences: readonly ReservedKeyOffence[], reserved: ReadonlyMap<string, ReservedKey>): string;
+//# sourceMappingURL=reserved-keys.d.ts.map

package/dist/reserved-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reserved-keys.d.ts","sourceRoot":"","sources":["../src/reserved-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,sGAAsG;AACtG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,SAAS;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,QAAQ,CAAA;SAAE,EAAE,CAAC;QAChF,oFAAoF;QACpF,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACjC,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAW9F;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,2FAA2F;IAC3F,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,oEAAoE;IACpE,KAAK,CAAC,EAAE,IAAI,CAAC;CACd;AAED,0GAA0G;AAC1G,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;KAAE,EAAE,CAAC;IAChG,MAAM,EAAE,SAAS;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC1E,2GAA2G;IAC3G,YAAY,CAAC,EAAE,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CAC7E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAC7B;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,CAOrD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAQ9F;AAED,2GAA2G;AAC3G,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAAG,kBAAkB,EAAE,CA4B9H;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,kBAAkB,EAAE,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,MAAM,CAS1G;AAED,0GAA0G;AAC1G,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GACzC,MAAM,CAuBR"}

package/dist/reserved-keys.js

@@ -0,0 +1,142 @@
+/**
+ * Keys no person may hold (#2425, #2430): the one reading of `holder: 'system'` on a manifest's
+ * permission declaration, applied wherever a permission surface is judged. `lint:permissions`
+ * (`tools/reserved-keys.mts`), `buildPermissionRegistry` and so `substrat push`, the push boundary
+ * (`pushedPermissionRegistry`), and a scope host's role doors (the kernel's `reservedRoleRefusal`)
+ * all call these, so none of them can read the mark differently.
+ *
+ * A vertical's person-facing surface is its `ROLES` and its `ENTITY_GRANTS` shapes (what a
+ * principal is handed per entity). A module's SYSTEM principal is a different declaration:
+ * `manifest.schedules[].permissions` (`system:<module>`) and `manifest.peers[].permissions`
+ * (`vertical:<slug>`). So "a system-only key" needs no new concept in the surface: it may appear
+ * in the second place and never in the first. The one role that may carry one is a role declared
+ * `holder: 'system'` (K-55), and it may carry nothing else.
+ *
+ * This is NOT the purge-only notion of K-45 (`entity-trash.ts`): that scopes a key a system
+ * principal already holds to one schedule's call. It says where a system principal may USE a key,
+ * not that a person may not be given it.
+ *
+ * Pure and dependency-free, so `tools/` can load it from source.
+ */
+/**
+ * Every key a manifest declares `holder: 'system'`.
+ *
+ * A union, not a vote: one module declaring the key reserved reserves it, whatever another module
+ * declaring the same key says. Otherwise a vertical could lift an engine's reservation by
+ * re-declaring the key, unmarked, in a module of its own.
+ */
+export function reservedKeysOf(modules) {
+    const seen = new Map();
+    for (const m of modules) {
+        for (const p of m.manifest.permissions) {
+            if (p.holder !== 'system')
+                continue;
+            let key = seen.get(p.key);
+            if (!key)
+                seen.set(p.key, (key = { description: p.description, declaredBy: new Set() }));
+            key.declaredBy.add(m.manifest.id);
+        }
+    }
+    return new Map([...seen].map(([k, v]) => [k, { description: v.description, declaredBy: [...v.declaredBy].sort() }]));
+}
+/**
+ * #2430: the owner grants a vertical declares, as named person grants — each module manifest's
+ * `ownerGrants` and, when given, the deployment's own `substrat.ownerGrants` (package.json). An
+ * install grants them to its owner, a person, so a reserved key among them is a person's grant.
+ */
+export function ownerGrantSets(modules, deployment) {
+    return [
+        ...modules
+            .filter((m) => m.manifest.ownerGrants?.length)
+            .map((m) => ({ where: `owner grants of ${m.manifest.id}`, permissions: m.manifest.ownerGrants })),
+        ...(deployment?.length ? [{ where: 'owner grants (substrat.ownerGrants)', permissions: deployment }] : []),
+    ];
+}
+/**
+ * #2430: package.json `substrat.ownerGrants` as the owner-grant list `ownerGrantSets` takes, or why
+ * it is not one. Absent is no owner grant; anything but an array of keys is a broken declaration,
+ * refused rather than read as none, since what it means to grant is exactly what cannot be judged.
+ */
+export function declaredOwnerGrants(value) {
+    if (value === undefined)
+        return { grants: [] };
+    if (Array.isArray(value) && value.every((k) => typeof k === 'string'))
+        return { grants: value };
+    return {
+        problem: `declares \`substrat.ownerGrants\` as ${JSON.stringify(value)}, not an array of permission keys. List the keys a ` +
+            'fresh install\'s owner is granted (`"ownerGrants": ["todo:list-create"]`), or leave the field out',
+    };
+}
+/** Every person-facing grant of a reserved key, and every malformed system-held role, in surface order. */
+export function reservedKeyOffences(surface, reserved) {
+    const out = [];
+    for (const r of surface.roles) {
+        // A system-held role that holds no reserved key is a standing principal granting nothing
+        // today and widenable by editing only the permission list: refuse it as vacuous.
+        if (r.holder === 'system' && !r.permissions.some((p) => reserved.has(p))) {
+            out.push({ where: `system-held role ${r.key}`, key: '(none)', notReserved: true, empty: true });
+        }
+        for (const p of r.permissions) {
+            // A system-held role (K-55) is the one role shape that may carry a reserved key. It may
+            // carry NOTHING ELSE: a standing host principal's authority is exactly the keys reserved
+            // to it, so a person-grade key slipped in beside them is an offence of its own.
+            if (r.holder === 'system') {
+                if (!reserved.has(p))
+                    out.push({ where: `system-held role ${r.key}`, key: p, notReserved: true });
+            }
+            else if (reserved.has(p))
+                out.push({ where: `role ${r.key}`, key: p });
+        }
+    }
+    for (const g of surface.grants) {
+        for (const p of g.permissions) {
+            if (reserved.has(p))
+                out.push({ where: `grant shape on ${g.entityType}`, key: p });
+        }
+    }
+    for (const g of surface.personGrants ?? []) {
+        for (const p of g.permissions) {
+            if (reserved.has(p))
+                out.push({ where: g.where, key: p });
+        }
+    }
+    return out;
+}
+/**
+ * One offence on one line: where, which key, and why it is refused. `reserved` names the module
+ * that marks the key; without it (the push boundary, which has only the registry's rows, whose
+ * `declaredBy` lists every declarer, marked or not) the line attributes the mark to nobody.
+ */
+export function reservedKeyLine(o, reserved) {
+    if (o.empty)
+        return `${o.where} → ${o.key}: a system-held role must hold at least one key reserved to a system principal`;
+    if (o.notReserved) {
+        return `${o.where} → ${o.key}: a system-held role holds only keys reserved to a system principal (a key its module declares \`holder: 'system'\`)`;
+    }
+    const r = reserved?.get(o.key);
+    return r
+        ? `${o.where} → ${o.key}: declared \`holder: 'system'\` by ${r.declaredBy.join(', ')} (${r.description})`
+        : `${o.where} → ${o.key}: reserved to a system principal (\`holder: 'system'\` on its registry row)`;
+}
+/** The refusal's text, naming the vertical, the file, each grant, who reserved the key and the remedy. */
+export function reservedKeyMessage(rel, entry, offences, reserved) {
+    const person = offences.filter((o) => !o.notReserved);
+    const system = offences.filter((o) => o.notReserved);
+    const lines = (os) => os.map((o) => `    ${reservedKeyLine(o, reserved)}`).join('\n');
+    const parts = [];
+    if (person.length) {
+        parts.push(`${rel}/${entry} grants a key reserved to a system principal to a person's role, grant shape or owner grant:\n` +
+            lines(person) +
+            `\n\n  Remedy: take the key out of the role, shape or owner grant. A module's own system principal gets it\n` +
+            `  from a schedule's \`permissions\` (or a peer's); a platform host's standing principal gets it\n` +
+            `  from a role declared \`holder: 'system'\` (K-55). Never from a role a person can hold.`);
+    }
+    if (system.length) {
+        parts.push(`${rel}/${entry} declares a system-held role that is not made of keys reserved to a system principal:\n` +
+            lines(system) +
+            `\n\n  Remedy: keep only reserved keys in a \`holder: 'system'\` role (and at least one), and move any\n` +
+            `  person-grade key to a role a person can hold.`);
+    }
+    return parts.join('\n\n');
+}
+//# sourceMappingURL=reserved-keys.js.map

package/dist/reserved-keys.js.map

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

package/dist/social-relay.d.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+/**
+ * PLATFORM-PROVIDED social sign-in for a team Auth Server (#1544).
+ *
+ * The platform's social relay (`apps/social-relay`, id.substrat.net) holds one OAuth client per
+ * upstream — Google, GitHub, Apple — and serves one OpenID issuer per provider in front of them.
+ * Each Auth Server install gets its OWN client at the relay, registered by the platform, never by
+ * the install: the redirect URIs are built from hostnames the platform issued or bound.
+ *
+ * This module is the vocabulary the control plane's reconciler and the Auth Server share. The
+ * reconciler delivers one entry through the issuer's platform-gated `/internal/configure`:
+ *
+ *     substrat:social-relay  =  { "clientId": "…", "clientSecret": "…",
+ *                                 "providers": [{ "id": "github", "label": "GitHub",
+ *                                                 "issuer": "https://id.substrat.net/github",
+ *                                                 "endpoints": { … } }, …] }
+ *
+ * The value is the WHOLE set of providers the relay serves, not a delta, so re-sending it is a
+ * no-op and a provider that drops out is switched off. `demos/auth-server/src/social-relay.ts`
+ * turns it into provider rows, each named `relayProviderId(id)`, created switched off.
+ *
+ * `clientSecret` is present only when the platform has one to give — when the relay client was
+ * just created, or its secret just rotated. The relay stores secrets hashed and cannot hand an
+ * existing one back, so an ordinary re-delivery carries none and the issuer keeps the one it
+ * holds. An issuer that holds none answers `SOCIAL_RELAY_SECRET_NEEDED` (409), and only then
+ * does the platform rotate and deliver again. Rotating on every delivery instead would let two
+ * overlapping reconciles deliver secrets out of order and leave the older one in place.
+ */
+export declare const SOCIAL_RELAY_CONFIG_KEY = "substrat:social-relay";
+/**
+ * The verticals the reconciler registers at the relay. Exact slugs, never a pattern: a
+ * registration spends the platform's upstream client, so only the platform's own issuer
+ * gets one — a builder's vertical that happens to be named the same lives under
+ * `<tenant>/<name>` and is not matched.
+ */
+export declare const SOCIAL_RELAY_VERTICALS: readonly string[];
+/**
+ * The provider id an install holds a relay provider under. Suffixed, because the bare ids
+ * (`github`, `google`, `apple`) are Better Auth's built-in providers, which an install may
+ * also configure with its own credential.
+ */
+export declare function relayProviderId(upstream: string): string;
+/** The path an Auth Server answers a provider's callback on (`callbackPath` in the issuer). */
+export declare function relayCallbackPath(upstream: string): string;
+/** The discovery endpoints the issuer stores on a generic row; the relay states them. */
+export declare const socialRelayEndpoints: z.ZodObject<{
+    issuer: z.ZodString;
+    authorization_endpoint: z.ZodString;
+    token_endpoint: z.ZodString;
+    userinfo_endpoint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SocialRelayEndpoints = z.infer<typeof socialRelayEndpoints>;
+/** One provider the relay serves, as `GET /providers` lists it and the delivery carries it. */
+export declare const socialRelayProvider: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    issuer: z.ZodString;
+    endpoints: z.ZodObject<{
+        issuer: z.ZodString;
+        authorization_endpoint: z.ZodString;
+        token_endpoint: z.ZodString;
+        userinfo_endpoint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SocialRelayProvider = z.infer<typeof socialRelayProvider>;
+export declare const socialRelayProviders: z.ZodObject<{
+    providers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        issuer: z.ZodString;
+        endpoints: z.ZodObject<{
+            issuer: z.ZodString;
+            authorization_endpoint: z.ZodString;
+            token_endpoint: z.ZodString;
+            userinfo_endpoint: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** What an issuer answers (409, as the `error`) when a delivery carries no secret and it holds none. */
+export declare const SOCIAL_RELAY_SECRET_NEEDED = "social_relay_secret_needed";
+/** The delivered value of `substrat:social-relay`. */
+export declare const socialRelayDelivery: z.ZodObject<{
+    clientId: z.ZodString;
+    clientSecret: z.ZodOptional<z.ZodString>;
+    providers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        issuer: z.ZodString;
+        endpoints: z.ZodObject<{
+            issuer: z.ZodString;
+            authorization_endpoint: z.ZodString;
+            token_endpoint: z.ZodString;
+            userinfo_endpoint: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SocialRelayDelivery = z.infer<typeof socialRelayDelivery>;
+//# sourceMappingURL=social-relay.d.ts.map

package/dist/social-relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"social-relay.d.ts","sourceRoot":"","sources":["../src/social-relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAoB,CAAC;AAEzE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,yFAAyF;AACzF,eAAO,MAAM,oBAAoB;;;;;iBAK/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,+FAA+F;AAC/F,eAAO,MAAM,mBAAmB;;;;;;;;;;iBAK9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;iBAAgE,CAAC;AAElG,wGAAwG;AACxG,eAAO,MAAM,0BAA0B,+BAA+B,CAAC;AAEvE,sDAAsD;AACtD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;iBAI9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/social-relay.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+/**
+ * PLATFORM-PROVIDED social sign-in for a team Auth Server (#1544).
+ *
+ * The platform's social relay (`apps/social-relay`, id.substrat.net) holds one OAuth client per
+ * upstream — Google, GitHub, Apple — and serves one OpenID issuer per provider in front of them.
+ * Each Auth Server install gets its OWN client at the relay, registered by the platform, never by
+ * the install: the redirect URIs are built from hostnames the platform issued or bound.
+ *
+ * This module is the vocabulary the control plane's reconciler and the Auth Server share. The
+ * reconciler delivers one entry through the issuer's platform-gated `/internal/configure`:
+ *
+ *     substrat:social-relay  =  { "clientId": "…", "clientSecret": "…",
+ *                                 "providers": [{ "id": "github", "label": "GitHub",
+ *                                                 "issuer": "https://id.substrat.net/github",
+ *                                                 "endpoints": { … } }, …] }
+ *
+ * The value is the WHOLE set of providers the relay serves, not a delta, so re-sending it is a
+ * no-op and a provider that drops out is switched off. `demos/auth-server/src/social-relay.ts`
+ * turns it into provider rows, each named `relayProviderId(id)`, created switched off.
+ *
+ * `clientSecret` is present only when the platform has one to give — when the relay client was
+ * just created, or its secret just rotated. The relay stores secrets hashed and cannot hand an
+ * existing one back, so an ordinary re-delivery carries none and the issuer keeps the one it
+ * holds. An issuer that holds none answers `SOCIAL_RELAY_SECRET_NEEDED` (409), and only then
+ * does the platform rotate and deliver again. Rotating on every delivery instead would let two
+ * overlapping reconciles deliver secrets out of order and leave the older one in place.
+ */
+export const SOCIAL_RELAY_CONFIG_KEY = 'substrat:social-relay';
+/**
+ * The verticals the reconciler registers at the relay. Exact slugs, never a pattern: a
+ * registration spends the platform's upstream client, so only the platform's own issuer
+ * gets one — a builder's vertical that happens to be named the same lives under
+ * `<tenant>/<name>` and is not matched.
+ */
+export const SOCIAL_RELAY_VERTICALS = ['auth-server'];
+/**
+ * The provider id an install holds a relay provider under. Suffixed, because the bare ids
+ * (`github`, `google`, `apple`) are Better Auth's built-in providers, which an install may
+ * also configure with its own credential.
+ */
+export function relayProviderId(upstream) {
+    return `${upstream}-relay`;
+}
+/** The path an Auth Server answers a provider's callback on (`callbackPath` in the issuer). */
+export function relayCallbackPath(upstream) {
+    return `/api/auth/callback/${relayProviderId(upstream)}`;
+}
+/** The discovery endpoints the issuer stores on a generic row; the relay states them. */
+export const socialRelayEndpoints = z.object({
+    issuer: z.string().url(),
+    authorization_endpoint: z.string().url(),
+    token_endpoint: z.string().url(),
+    userinfo_endpoint: z.string().url().optional(),
+});
+/** One provider the relay serves, as `GET /providers` lists it and the delivery carries it. */
+export const socialRelayProvider = z.object({
+    id: z.string().regex(/^[a-z0-9]{1,32}$/),
+    label: z.string().min(1).max(100),
+    issuer: z.string().url(),
+    endpoints: socialRelayEndpoints,
+});
+export const socialRelayProviders = z.object({ providers: z.array(socialRelayProvider).max(32) });
+/** What an issuer answers (409, as the `error`) when a delivery carries no secret and it holds none. */
+export const SOCIAL_RELAY_SECRET_NEEDED = 'social_relay_secret_needed';
+/** The delivered value of `substrat:social-relay`. */
+export const socialRelayDelivery = z.object({
+    clientId: z.string().min(1).max(200),
+    clientSecret: z.string().min(1).max(500).optional(),
+    providers: z.array(socialRelayProvider).max(32),
+});
+//# sourceMappingURL=social-relay.js.map

package/dist/social-relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"social-relay.js","sourceRoot":"","sources":["../src/social-relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,uBAAuB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB,CAAC,aAAa,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,GAAG,QAAQ,QAAQ,CAAC;AAC7B,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,OAAO,sBAAsB,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;AAC3D,CAAC;AAED,yFAAyF;AACzF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACxB,sBAAsB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACxC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAChC,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CAC/C,CAAC,CAAC;AAGH,+FAA+F;AAC/F,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC;IACxC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACjC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACxB,SAAS,EAAE,oBAAoB;CAChC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;AAElG,wGAAwG;AACxG,MAAM,CAAC,MAAM,0BAA0B,GAAG,4BAA4B,CAAC;AAEvE,sDAAsD;AACtD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACpC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IACnD,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;CAChD,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/contracts",
-  "version": "0.153.0",
+  "version": "0.154.0",
   "description": "Substrat kernel contract schemas — Zod is the source of truth (master plan D-22); OAS/JSON Schema are emitted artifacts",
   "license": "Apache-2.0",
   "repository": {