@cat-factory/contracts 0.246.0 → 0.247.0

package/dist/sso.d.ts

@@ -0,0 +1,70 @@
+import * as v from 'valibot';
+/**
+ * The SSO protocols the adapter speaks.
+ *
+ * `oidc` covers every provider that exposes an OpenID Connect discovery document, which is all
+ * of the hosted directories and a Shibboleth IdP with the OIDC OP plugin installed. A classic
+ * SAML-2.0-only Shibboleth deployment is NOT served by it and is deliberately absent rather
+ * than approximated: see `docs/initiatives/enterprise-sso-oidc.md`. Adding `saml` here is what
+ * that slice extends, and every switch over this union fails to compile until it is handled.
+ */
+export declare const ssoProtocolSchema: v.PicklistSchema<["oidc"], undefined>;
+export type SsoProtocol = v.InferOutput<typeof ssoProtocolSchema>;
+/**
+ * What `GET /auth/config` reports about the configured provider, so the login screen can render
+ * the operator's own wording ("Sign in with Acme SSO") instead of a generic button. Present only
+ * when SSO is configured; `providers.sso` is the boolean the SPA gates on.
+ */
+export declare const ssoConfigViewSchema: v.ObjectSchema<{
+    /** Operator-supplied button label (`AUTH_SSO_LABEL`), never localized — it names their IdP. */
+    readonly label: v.StringSchema<undefined>;
+    readonly protocol: v.PicklistSchema<["oidc"], undefined>;
+}, undefined>;
+export type SsoConfigView = v.InferOutput<typeof ssoConfigViewSchema>;
+/**
+ * Why an SSO sign-in did not produce a session. Each member is a DIFFERENT operator or user
+ * action, which is the whole reason the vocabulary is not one `sso_failed`:
+ *
+ * - `state_invalid` — the round-trip's signed state / browser-binding cookie didn't verify.
+ *   A stale bookmark, a cookie-less browser, or a genuinely forged callback. Retrying works.
+ * - `provider_denied` — the IdP itself refused (`?error=access_denied` …): the user cancelled,
+ *   or the app is not assigned to them. Nothing on this side to fix.
+ * - `exchange_failed` — the code-for-token call failed. A wrong client secret or a
+ *   `redirect_uri` the IdP does not have registered: an OPERATOR fault, not the user's.
+ * - `token_invalid` — the ID token failed verification (signature, issuer, audience, nonce or
+ *   expiry). A misconfigured client id, a clock skew, or an attack.
+ * - `subject_missing` — the token verified but carries no `sub`, so there is no stable identity
+ *   to key a user on. A non-conforming provider.
+ * - `group_required` — the user authenticated but is in none of `AUTH_SSO_REQUIRED_GROUPS`.
+ *   The user needs a directory group, and the message must say so rather than read as a bug.
+ * - `domain_not_allowed` — their verified email's domain is not on
+ *   `AUTH_SSO_ALLOWED_EMAIL_DOMAINS`. Distinct from `group_required` because the remedy differs.
+ * - `email_required` — an email-domain allowlist is configured but the provider released no
+ *   verified email to check it against, so admission cannot be decided. An operator must
+ *   release the `email` claim (or drop the allowlist); admitting instead would silently void it.
+ * - `provider_unreachable` — the IdP (or the network to it) did not answer while the callback was
+ *   being settled: its discovery document or key set could not be read. An OUTAGE, distinct from
+ *   `exchange_failed` because the remedy is not the deployment's own client credentials, and
+ *   distinct from `token_invalid` because nothing was wrong with the token. Retrying works once
+ *   the provider does.
+ */
+export declare const ssoErrorReasonSchema: v.PicklistSchema<["state_invalid", "provider_denied", "exchange_failed", "token_invalid", "subject_missing", "group_required", "domain_not_allowed", "email_required", "provider_unreachable"], undefined>;
+export type SsoErrorReason = v.InferOutput<typeof ssoErrorReasonSchema>;
+/** Every reason, for the SPA's exhaustive copy `Record` and the coverage test over it. */
+export declare const SSO_ERROR_REASONS: ["state_invalid", "provider_denied", "exchange_failed", "token_invalid", "subject_missing", "group_required", "domain_not_allowed", "email_required", "provider_unreachable"];
+/**
+ * The URL-fragment key a failed SSO round-trip lands under, the sibling of the `token=` key a
+ * successful one uses. A FRAGMENT (not a query) for the same reason the token is: it never
+ * reaches a server log or a `Referer` header, and the reason names the deployment's admission
+ * rules. Shared so the redirect builder and the SPA reader cannot drift.
+ */
+export declare const SSO_ERROR_FRAGMENT_KEY = "sso_error";
+/**
+ * Read a reason off an untrusted string, or null when it names none.
+ *
+ * Total by construction (derived from the picklist's own options), so a member added above is
+ * parseable with no edit here — and a value from a NEWER backend than the SPA reads as "unknown
+ * failure" rather than being rendered as the literal wire token.
+ */
+export declare function parseSsoErrorReason(value: string | null | undefined): SsoErrorReason | null;
+//# sourceMappingURL=sso.d.ts.map

package/dist/sso.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso.d.ts","sourceRoot":"","sources":["../src/sso.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAiB5B;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,uCAAuB,CAAA;AACrD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEjE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;IAC9B,+FAA+F;;;aAG/F,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,oBAAoB,4MAU/B,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,0FAA0F;AAC1F,eAAO,MAAM,iBAAiB,+KAA+B,CAAA;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,cAAc,CAAA;AAEjD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,GAAG,IAAI,CAG3F"}

package/dist/sso.js

@@ -0,0 +1,95 @@
+import * as v from 'valibot';
+// ---------------------------------------------------------------------------
+// Enterprise SSO: the wire vocabulary the backend and the SPA must agree about.
+//
+// Sign-in through a deployment's OWN identity provider (Okta, Entra ID, Auth0, Keycloak,
+// PingFederate, OneLogin, JumpCloud, a Shibboleth IdP running the OIDC OP plugin) rather than
+// through a consumer provider. One generic adapter serves all of them: a discovery document
+// plus a client id/secret is the entire configuration, so there is nothing per-vendor to name
+// here — only the PROTOCOL, which is what a second adapter would extend.
+//
+// A failed SSO round-trip lands the browser back on the SPA with a machine-readable reason in
+// the URL fragment rather than a JSON envelope the user would have to read raw. The backend
+// does not localize prose (CLAUDE.md's i18n rule), so the vocabulary is closed here and the SPA
+// maps each member to translated copy through an exhaustive `Record`.
+// ---------------------------------------------------------------------------
+/**
+ * The SSO protocols the adapter speaks.
+ *
+ * `oidc` covers every provider that exposes an OpenID Connect discovery document, which is all
+ * of the hosted directories and a Shibboleth IdP with the OIDC OP plugin installed. A classic
+ * SAML-2.0-only Shibboleth deployment is NOT served by it and is deliberately absent rather
+ * than approximated: see `docs/initiatives/enterprise-sso-oidc.md`. Adding `saml` here is what
+ * that slice extends, and every switch over this union fails to compile until it is handled.
+ */
+export const ssoProtocolSchema = v.picklist(['oidc']);
+/**
+ * What `GET /auth/config` reports about the configured provider, so the login screen can render
+ * the operator's own wording ("Sign in with Acme SSO") instead of a generic button. Present only
+ * when SSO is configured; `providers.sso` is the boolean the SPA gates on.
+ */
+export const ssoConfigViewSchema = v.object({
+    /** Operator-supplied button label (`AUTH_SSO_LABEL`), never localized — it names their IdP. */
+    label: v.string(),
+    protocol: ssoProtocolSchema,
+});
+/**
+ * Why an SSO sign-in did not produce a session. Each member is a DIFFERENT operator or user
+ * action, which is the whole reason the vocabulary is not one `sso_failed`:
+ *
+ * - `state_invalid` — the round-trip's signed state / browser-binding cookie didn't verify.
+ *   A stale bookmark, a cookie-less browser, or a genuinely forged callback. Retrying works.
+ * - `provider_denied` — the IdP itself refused (`?error=access_denied` …): the user cancelled,
+ *   or the app is not assigned to them. Nothing on this side to fix.
+ * - `exchange_failed` — the code-for-token call failed. A wrong client secret or a
+ *   `redirect_uri` the IdP does not have registered: an OPERATOR fault, not the user's.
+ * - `token_invalid` — the ID token failed verification (signature, issuer, audience, nonce or
+ *   expiry). A misconfigured client id, a clock skew, or an attack.
+ * - `subject_missing` — the token verified but carries no `sub`, so there is no stable identity
+ *   to key a user on. A non-conforming provider.
+ * - `group_required` — the user authenticated but is in none of `AUTH_SSO_REQUIRED_GROUPS`.
+ *   The user needs a directory group, and the message must say so rather than read as a bug.
+ * - `domain_not_allowed` — their verified email's domain is not on
+ *   `AUTH_SSO_ALLOWED_EMAIL_DOMAINS`. Distinct from `group_required` because the remedy differs.
+ * - `email_required` — an email-domain allowlist is configured but the provider released no
+ *   verified email to check it against, so admission cannot be decided. An operator must
+ *   release the `email` claim (or drop the allowlist); admitting instead would silently void it.
+ * - `provider_unreachable` — the IdP (or the network to it) did not answer while the callback was
+ *   being settled: its discovery document or key set could not be read. An OUTAGE, distinct from
+ *   `exchange_failed` because the remedy is not the deployment's own client credentials, and
+ *   distinct from `token_invalid` because nothing was wrong with the token. Retrying works once
+ *   the provider does.
+ */
+export const ssoErrorReasonSchema = v.picklist([
+    'state_invalid',
+    'provider_denied',
+    'exchange_failed',
+    'token_invalid',
+    'subject_missing',
+    'group_required',
+    'domain_not_allowed',
+    'email_required',
+    'provider_unreachable',
+]);
+/** Every reason, for the SPA's exhaustive copy `Record` and the coverage test over it. */
+export const SSO_ERROR_REASONS = ssoErrorReasonSchema.options;
+/**
+ * The URL-fragment key a failed SSO round-trip lands under, the sibling of the `token=` key a
+ * successful one uses. A FRAGMENT (not a query) for the same reason the token is: it never
+ * reaches a server log or a `Referer` header, and the reason names the deployment's admission
+ * rules. Shared so the redirect builder and the SPA reader cannot drift.
+ */
+export const SSO_ERROR_FRAGMENT_KEY = 'sso_error';
+/**
+ * Read a reason off an untrusted string, or null when it names none.
+ *
+ * Total by construction (derived from the picklist's own options), so a member added above is
+ * parseable with no edit here — and a value from a NEWER backend than the SPA reads as "unknown
+ * failure" rather than being rendered as the literal wire token.
+ */
+export function parseSsoErrorReason(value) {
+    if (!value)
+        return null;
+    return SSO_ERROR_REASONS.includes(value) ? value : null;
+}
+//# sourceMappingURL=sso.js.map

package/dist/sso.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso.js","sourceRoot":"","sources":["../src/sso.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,8EAA8E;AAC9E,gFAAgF;AAChF,EAAE;AACF,yFAAyF;AACzF,8FAA8F;AAC9F,4FAA4F;AAC5F,8FAA8F;AAC9F,yEAAyE;AACzE,EAAE;AACF,8FAA8F;AAC9F,4FAA4F;AAC5F,gGAAgG;AAChG,sEAAsE;AACtE,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;AAGrD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,+FAA+F;IAC/F,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,QAAQ,EAAE,iBAAiB;CAC5B,CAAC,CAAA;AAGF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,QAAQ,CAAC;IAC7C,eAAe;IACf,iBAAiB;IACjB,iBAAiB;IACjB,eAAe;IACf,iBAAiB;IACjB,gBAAgB;IAChB,oBAAoB;IACpB,gBAAgB;IAChB,sBAAsB;CACvB,CAAC,CAAA;AAGF,0FAA0F;AAC1F,MAAM,CAAC,MAAM,iBAAiB,GAAG,oBAAoB,CAAC,OAAO,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAA;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAgC;IAClE,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IACvB,OAAQ,iBAAuC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAwB,CAAC,CAAC,CAAC,IAAI,CAAA;AACpG,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/contracts",
-  "version": "0.246.0",
+  "version": "0.247.0",
   "description": "Valibot wire contract shared between the Agent Architecture Board frontend and backend.",
   "repository": {
     "type": "git",