@endora-commerce/contracts 0.100.0

package/dist/mfa.d.ts

@@ -0,0 +1,274 @@
+import { z } from 'zod';
+/** Identity surface a subject belongs to. */
+export declare const mfaSubjectTypeSchema: z.ZodEnum<{
+    customer: "customer";
+    admin: "admin";
+}>;
+export type MfaSubjectType = z.infer<typeof mfaSubjectTypeSchema>;
+/** Supported federated identity providers. */
+export declare const mfaSocialProviderSchema: z.ZodEnum<{
+    google: "google";
+    microsoft: "microsoft";
+}>;
+export type MfaSocialProvider = z.infer<typeof mfaSocialProviderSchema>;
+/**
+ * `GET /api/v1/auth/{customer|admin}/oauth/providers` — public, unauthenticated.
+ *
+ * The providers a sign-in surface can actually complete a hand-off with. A
+ * provider is listed only when **both** halves hold: client credentials are
+ * configured for it (backend env, never Settings) *and* the surface's
+ * `mfa.*.<provider>_enabled` setting is on for the request's sales channel.
+ *
+ * A provider missing either half is **absent from the array**, not present with
+ * a `false` flag. That asymmetry is the contract's job: a frontend deciding
+ * "render this button or not" must not be handed a reason to render a control
+ * whose click leads back to the login screen with an error. Both settings
+ * default to `false`, so the honest answer on a fresh deployment is `[]`.
+ *
+ * The route belongs to `mfa` and is gated at its registration seam, so a
+ * switched-off module answers 503 `MODULE_DISABLED`. Frontends still project
+ * absence from `/module-presence` first and treat the 503 as defence in depth —
+ * absence is projected, never inferred from a status code.
+ */
+export declare const federatedSignInOptionsResponseSchema: z.ZodObject<{
+    providers: z.ZodArray<z.ZodEnum<{
+        google: "google";
+        microsoft: "microsoft";
+    }>>;
+}, z.core.$strip>;
+export type FederatedSignInOptionsResponse = z.infer<typeof federatedSignInOptionsResponseSchema>;
+/**
+ * Discriminated result returned by the first login step (email+password) and
+ * by the OAuth callback. Only `authenticated` carries/sets a session cookie;
+ * the other two hand the client an opaque ticket for the second step.
+ */
+export declare const mfaLoginResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"authenticated">;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"mfaRequired">;
+    challengeId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"mfaSetupRequired">;
+    setupTicket: z.ZodString;
+}, z.core.$strip>], "status">;
+export type MfaLoginResult = z.infer<typeof mfaLoginResultSchema>;
+/** Second-step verification — a 6-digit TOTP code or a recovery code. */
+export declare const mfaVerifyRequestSchema: z.ZodObject<{
+    challengeId: z.ZodString;
+    code: z.ZodString;
+}, z.core.$strip>;
+export type MfaVerifyRequest = z.infer<typeof mfaVerifyRequestSchema>;
+/** Optional setup ticket for the enforced-but-unenrolled flow (no session yet). */
+export declare const mfaSetupTicketBodySchema: z.ZodObject<{
+    setupTicket: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const mfaSetupResponseSchema: z.ZodObject<{
+    secret: z.ZodString;
+    otpauthUri: z.ZodString;
+}, z.core.$strip>;
+export type MfaSetupResponse = z.infer<typeof mfaSetupResponseSchema>;
+export declare const mfaActivateRequestSchema: z.ZodObject<{
+    code: z.ZodString;
+    setupTicket: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MfaActivateRequest = z.infer<typeof mfaActivateRequestSchema>;
+export declare const mfaActivateResponseSchema: z.ZodObject<{
+    recoveryCodes: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type MfaActivateResponse = z.infer<typeof mfaActivateResponseSchema>;
+/**
+ * Enforced-but-unenrolled flow (feature 042, US3). The setup ticket replaces a
+ * session for the forced-enrolment screen: `begin` returns the secret, and
+ * `complete` activates + upgrades the ticket to a full session.
+ */
+export declare const mfaSetupTicketBeginSchema: z.ZodObject<{
+    setupTicket: z.ZodString;
+}, z.core.$strip>;
+export type MfaSetupTicketBegin = z.infer<typeof mfaSetupTicketBeginSchema>;
+export declare const mfaSetupTicketCompleteSchema: z.ZodObject<{
+    setupTicket: z.ZodString;
+    code: z.ZodString;
+}, z.core.$strip>;
+export type MfaSetupTicketComplete = z.infer<typeof mfaSetupTicketCompleteSchema>;
+/** Re-auth for self-disable: current password, or a current TOTP/recovery code. */
+export declare const mfaDisableRequestSchema: z.ZodObject<{
+    password: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MfaDisableRequest = z.infer<typeof mfaDisableRequestSchema>;
+export declare const mfaRegenerateRequestSchema: z.ZodObject<{
+    code: z.ZodString;
+}, z.core.$strip>;
+export type MfaRegenerateRequest = z.infer<typeof mfaRegenerateRequestSchema>;
+/**
+ * Why an account may not sever a federated identity (issue #194).
+ *
+ * `last_credential` — it is the account's only link, and the platform cannot
+ * tell whether its holder has ever chosen a password: an account created by a
+ * social sign-in is given a random one at signup. Removing the link could
+ * therefore remove the only credential its holder can use, so it is refused
+ * until another credential is in place.
+ */
+export declare const mfaSocialUnlinkBlockedReasonSchema: z.ZodEnum<{
+    last_credential: "last_credential";
+}>;
+export type MfaSocialUnlinkBlockedReason = z.infer<typeof mfaSocialUnlinkBlockedReasonSchema>;
+export declare const mfaSocialLinkSummarySchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        google: "google";
+        microsoft: "microsoft";
+    }>;
+    email: z.ZodString;
+    linkedAt: z.ZodString;
+    canUnlink: z.ZodBoolean;
+    unlinkBlockedReason: z.ZodNullable<z.ZodEnum<{
+        last_credential: "last_credential";
+    }>>;
+}, z.core.$strip>;
+export type MfaSocialLinkSummary = z.infer<typeof mfaSocialLinkSummarySchema>;
+/** `DELETE {prefix}/social-links/:provider` — one link per provider per account. */
+export declare const mfaSocialUnlinkParamsSchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        google: "google";
+        microsoft: "microsoft";
+    }>;
+}, z.core.$strip>;
+export type MfaSocialUnlinkParams = z.infer<typeof mfaSocialUnlinkParamsSchema>;
+export declare const mfaSocialUnlinkResponseSchema: z.ZodObject<{
+    status: z.ZodLiteral<"unlinked">;
+    provider: z.ZodEnum<{
+        google: "google";
+        microsoft: "microsoft";
+    }>;
+}, z.core.$strip>;
+export type MfaSocialUnlinkResponse = z.infer<typeof mfaSocialUnlinkResponseSchema>;
+export declare const mfaStatusResponseSchema: z.ZodObject<{
+    totpActive: z.ZodBoolean;
+    recoveryCodesRemaining: z.ZodNumber;
+    totpEnabledForScope: z.ZodBoolean;
+    totpEnforcedForScope: z.ZodBoolean;
+    socialLinks: z.ZodArray<z.ZodObject<{
+        provider: z.ZodEnum<{
+            google: "google";
+            microsoft: "microsoft";
+        }>;
+        email: z.ZodString;
+        linkedAt: z.ZodString;
+        canUnlink: z.ZodBoolean;
+        unlinkBlockedReason: z.ZodNullable<z.ZodEnum<{
+            last_credential: "last_credential";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MfaStatusResponse = z.infer<typeof mfaStatusResponseSchema>;
+export declare const mfaOrgPolicyRequestSchema: z.ZodObject<{
+    enforceTotp: z.ZodBoolean;
+}, z.core.$strip>;
+export type MfaOrgPolicyRequest = z.infer<typeof mfaOrgPolicyRequestSchema>;
+export declare const mfaOrgPolicyResponseSchema: z.ZodObject<{
+    enforceTotp: z.ZodBoolean;
+}, z.core.$strip>;
+export type MfaOrgPolicyResponse = z.infer<typeof mfaOrgPolicyResponseSchema>;
+export declare const mfaResetBulkRequestSchema: z.ZodUnion<readonly [z.ZodObject<{
+    customerIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    organizationId: z.ZodString;
+}, z.core.$strip>]>;
+export type MfaResetBulkRequest = z.infer<typeof mfaResetBulkRequestSchema>;
+export declare const mfaResetResultSchema: z.ZodObject<{
+    affected: z.ZodBoolean;
+}, z.core.$strip>;
+export type MfaResetResult = z.infer<typeof mfaResetResultSchema>;
+export declare const mfaResetBulkResultSchema: z.ZodObject<{
+    requested: z.ZodNumber;
+    affected: z.ZodNumber;
+    skipped: z.ZodNumber;
+}, z.core.$strip>;
+export type MfaResetBulkResult = z.infer<typeof mfaResetBulkResultSchema>;
+export declare const MFA_SETTING_CODES: {
+    /**
+     * Feature 074 — the operator-activation control (Constitution XVII). It sits
+     * above the eight policy switches below rather than beside them: those decide
+     * *which* second factor a surface offers, this decides whether the module is
+     * present at all.
+     */
+    readonly ACTIVATION: "mfa.enabled";
+    readonly ADMIN_TOTP_ENABLED: "mfa.admin.totp_enabled";
+    readonly ADMIN_TOTP_ENFORCED: "mfa.admin.totp_enforced";
+    readonly STOREFRONT_TOTP_ENABLED: "mfa.storefront.totp_enabled";
+    readonly STOREFRONT_TOTP_ENFORCED: "mfa.storefront.totp_enforced";
+    readonly ADMIN_GOOGLE_ENABLED: "mfa.admin.google_enabled";
+    readonly ADMIN_MICROSOFT_ENABLED: "mfa.admin.microsoft_enabled";
+    readonly STOREFRONT_GOOGLE_ENABLED: "mfa.storefront.google_enabled";
+    readonly STOREFRONT_MICROSOFT_ENABLED: "mfa.storefront.microsoft_enabled";
+};
+/** How many subjects hold an active second factor, split by identity store. */
+export declare const mfaActiveEnrolmentCountsSchema: z.ZodObject<{
+    admins: z.ZodNumber;
+    customers: z.ZodNumber;
+}, z.core.$strip>;
+export type MfaActiveEnrolmentCounts = z.infer<typeof mfaActiveEnrolmentCountsSchema>;
+/**
+ * Container name: `mfaEnrolmentCountPort`. Owner: `mfa`.
+ *
+ * How many people would lose their second factor. Read by `/platform/modules`
+ * before an operator switches this module off, so the confirmation dialog can
+ * say "14 administrators and 320 customers currently use a second factor"
+ * instead of only naming the capability.
+ *
+ * **It is read while `mfa` is still on**, which is the whole reason it can be a
+ * port at all: the dialog renders before the flip, so the gate on this
+ * registration is open at exactly the moment the question is asked. A count
+ * taken *after* deactivation would be a read of `mfa_enrolments` through a
+ * closed gate, which is why "refuse the login of an enrolled subject while the
+ * module is off" was ruled unimplementable (D-96.7).
+ *
+ * The caller therefore decides presence before it resolves this, and treats a
+ * failed read as "count unavailable" — a number that cannot be fetched must
+ * never stop an operator switching a module off.
+ */
+export interface MfaEnrolmentCountPort {
+    /** Subjects with an `active` (confirmed) TOTP enrolment, right now. */
+    countActiveEnrolments(): Promise<MfaActiveEnrolmentCounts>;
+}
+/**
+ * Container name: `mfaEnrolmentStatePort`. Owner: `mfa`.
+ *
+ * Which of these subjects hold an **active** (confirmed) second factor, right
+ * now. It is the source `twoFactorEnabled` is derived from on every response
+ * that carries it — the admin user list and `/api/v1/admin/me`, the admin
+ * customer detail, the organisation member panels, and the buyer's own
+ * `GET /api/v1/me/customer`.
+ *
+ * Both identity stores hold a `two_factor_confirmed_at` column and **neither
+ * has ever had a writer**, so the field derived from it was a provably
+ * constant `false`: an operator, and a buyer reading their own account page,
+ * were told "no second factor" about someone who had enrolled an hour earlier.
+ * The live state is `mfa_enrolments`, which is this module's table, so this is
+ * the only honest source.
+ *
+ * **Batched, not per row.** The callers are list surfaces; a per-row port would
+ * put one query per admin user behind `/admin-users`. `subjectIds` is answered
+ * as a subset, so a caller builds a `Set` and asks it per row.
+ *
+ * The record is `string[]` and never an entity: `MfaEnrolment` carries the
+ * encrypted TOTP secret, its IV and its auth tag, and no consumer of this port
+ * has any business holding those.
+ *
+ * **When `mfa` is absent this port is not resolved at all.** The gate on the
+ * registration would refuse, and a 503 is the wrong answer for an admin list —
+ * so both consumers decide presence with `effectiveState.isPresent('mfa')`
+ * first and report `false`, which is not a fallback but the truth: with the
+ * module off, no sign-in asks for a second factor, so no account is protected
+ * by one. See the `degrades-without` entries in `admin_users`' and
+ * `customer_accounts`' manifests for the sentence an operator is shown.
+ */
+export interface MfaEnrolmentStatePort {
+    /**
+     * The subset of `subjectIds` with an `active` enrolment of `subjectType`.
+     * Order is not significant and an empty input answers an empty array without
+     * touching the database.
+     */
+    activeSubjectIds(subjectType: MfaSubjectType, subjectIds: readonly string[]): Promise<string[]>;
+}
+//# sourceMappingURL=mfa.d.ts.map

package/dist/mfa.d.ts.map

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

package/dist/mfa.js

@@ -0,0 +1,187 @@
+// @endora-commerce/contracts — MFA module (feature 042).
+//
+// Source-of-truth Zod schemas for the MFA boundary: TOTP enrolment/verification,
+// the two-step login result, federated sign-in, and admin reset/enforcement.
+// Provider client secrets are NOT modelled here — they are backend config/env.
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Shared enums
+// ---------------------------------------------------------------------------
+/** Identity surface a subject belongs to. */
+export const mfaSubjectTypeSchema = z.enum(['customer', 'admin']);
+/** Supported federated identity providers. */
+export const mfaSocialProviderSchema = z.enum(['google', 'microsoft']);
+// ---------------------------------------------------------------------------
+// Federated sign-in availability (issue #193)
+// ---------------------------------------------------------------------------
+/**
+ * `GET /api/v1/auth/{customer|admin}/oauth/providers` — public, unauthenticated.
+ *
+ * The providers a sign-in surface can actually complete a hand-off with. A
+ * provider is listed only when **both** halves hold: client credentials are
+ * configured for it (backend env, never Settings) *and* the surface's
+ * `mfa.*.<provider>_enabled` setting is on for the request's sales channel.
+ *
+ * A provider missing either half is **absent from the array**, not present with
+ * a `false` flag. That asymmetry is the contract's job: a frontend deciding
+ * "render this button or not" must not be handed a reason to render a control
+ * whose click leads back to the login screen with an error. Both settings
+ * default to `false`, so the honest answer on a fresh deployment is `[]`.
+ *
+ * The route belongs to `mfa` and is gated at its registration seam, so a
+ * switched-off module answers 503 `MODULE_DISABLED`. Frontends still project
+ * absence from `/module-presence` first and treat the 503 as defence in depth —
+ * absence is projected, never inferred from a status code.
+ */
+export const federatedSignInOptionsResponseSchema = z.object({
+    providers: z.array(mfaSocialProviderSchema),
+});
+// ---------------------------------------------------------------------------
+// Two-step login result (replaces the inline `twoFactorCode` shape)
+// ---------------------------------------------------------------------------
+/**
+ * Discriminated result returned by the first login step (email+password) and
+ * by the OAuth callback. Only `authenticated` carries/sets a session cookie;
+ * the other two hand the client an opaque ticket for the second step.
+ */
+export const mfaLoginResultSchema = z.discriminatedUnion('status', [
+    z.object({ status: z.literal('authenticated') }),
+    z.object({ status: z.literal('mfaRequired'), challengeId: z.string().min(1) }),
+    z.object({
+        status: z.literal('mfaSetupRequired'),
+        setupTicket: z.string().min(1),
+    }),
+]);
+/** Second-step verification — a 6-digit TOTP code or a recovery code. */
+export const mfaVerifyRequestSchema = z.object({
+    challengeId: z.string().min(1),
+    code: z.string().min(6).max(20),
+});
+// ---------------------------------------------------------------------------
+// Self-service enrolment
+// ---------------------------------------------------------------------------
+/** Optional setup ticket for the enforced-but-unenrolled flow (no session yet). */
+export const mfaSetupTicketBodySchema = z.object({
+    setupTicket: z.string().min(1).optional(),
+});
+export const mfaSetupResponseSchema = z.object({
+    /** base32 secret for manual entry. */
+    secret: z.string().min(1),
+    /** otpauth:// URI for QR rendering on the client. */
+    otpauthUri: z.string().min(1),
+});
+export const mfaActivateRequestSchema = z.object({
+    code: z.string().length(6),
+    setupTicket: z.string().min(1).optional(),
+});
+export const mfaActivateResponseSchema = z.object({
+    recoveryCodes: z.array(z.string()).length(10),
+});
+/**
+ * Enforced-but-unenrolled flow (feature 042, US3). The setup ticket replaces a
+ * session for the forced-enrolment screen: `begin` returns the secret, and
+ * `complete` activates + upgrades the ticket to a full session.
+ */
+export const mfaSetupTicketBeginSchema = z.object({
+    setupTicket: z.string().min(1),
+});
+export const mfaSetupTicketCompleteSchema = z.object({
+    setupTicket: z.string().min(1),
+    code: z.string().length(6),
+});
+/** Re-auth for self-disable: current password, or a current TOTP/recovery code. */
+export const mfaDisableRequestSchema = z
+    .object({
+    password: z.string().min(1).optional(),
+    code: z.string().min(6).max(20).optional(),
+})
+    .refine((v) => Boolean(v.password) || Boolean(v.code), {
+    message: 'Either password or code is required to disable 2FA.',
+});
+export const mfaRegenerateRequestSchema = z.object({
+    code: z.string().length(6),
+});
+/**
+ * Why an account may not sever a federated identity (issue #194).
+ *
+ * `last_credential` — it is the account's only link, and the platform cannot
+ * tell whether its holder has ever chosen a password: an account created by a
+ * social sign-in is given a random one at signup. Removing the link could
+ * therefore remove the only credential its holder can use, so it is refused
+ * until another credential is in place.
+ */
+export const mfaSocialUnlinkBlockedReasonSchema = z.enum(['last_credential']);
+export const mfaSocialLinkSummarySchema = z.object({
+    provider: mfaSocialProviderSchema,
+    email: z.string(),
+    linkedAt: z.string(),
+    /** The surface renders the unlink control from this, never from its own guess. */
+    canUnlink: z.boolean(),
+    unlinkBlockedReason: mfaSocialUnlinkBlockedReasonSchema.nullable(),
+});
+/** `DELETE {prefix}/social-links/:provider` — one link per provider per account. */
+export const mfaSocialUnlinkParamsSchema = z.object({
+    provider: mfaSocialProviderSchema,
+});
+export const mfaSocialUnlinkResponseSchema = z.object({
+    status: z.literal('unlinked'),
+    provider: mfaSocialProviderSchema,
+});
+export const mfaStatusResponseSchema = z.object({
+    totpActive: z.boolean(),
+    recoveryCodesRemaining: z.number().int().nonnegative(),
+    totpEnabledForScope: z.boolean(),
+    totpEnforcedForScope: z.boolean(),
+    socialLinks: z.array(mfaSocialLinkSummarySchema),
+});
+// ---------------------------------------------------------------------------
+// Organization enforcement policy
+// ---------------------------------------------------------------------------
+export const mfaOrgPolicyRequestSchema = z.object({
+    enforceTotp: z.boolean(),
+});
+export const mfaOrgPolicyResponseSchema = z.object({
+    enforceTotp: z.boolean(),
+});
+// ---------------------------------------------------------------------------
+// Admin reset
+// ---------------------------------------------------------------------------
+export const mfaResetBulkRequestSchema = z.union([
+    z.object({ customerIds: z.array(z.string().uuid()).min(1).max(1000) }),
+    z.object({ organizationId: z.string().uuid() }),
+]);
+export const mfaResetResultSchema = z.object({ affected: z.boolean() });
+export const mfaResetBulkResultSchema = z.object({
+    requested: z.number().int().nonnegative(),
+    affected: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative(),
+});
+// ---------------------------------------------------------------------------
+// Setting codes (single source for both manifest and resolver)
+// ---------------------------------------------------------------------------
+export const MFA_SETTING_CODES = {
+    /**
+     * Feature 074 — the operator-activation control (Constitution XVII). It sits
+     * above the eight policy switches below rather than beside them: those decide
+     * *which* second factor a surface offers, this decides whether the module is
+     * present at all.
+     */
+    ACTIVATION: 'mfa.enabled',
+    ADMIN_TOTP_ENABLED: 'mfa.admin.totp_enabled',
+    ADMIN_TOTP_ENFORCED: 'mfa.admin.totp_enforced',
+    STOREFRONT_TOTP_ENABLED: 'mfa.storefront.totp_enabled',
+    STOREFRONT_TOTP_ENFORCED: 'mfa.storefront.totp_enforced',
+    ADMIN_GOOGLE_ENABLED: 'mfa.admin.google_enabled',
+    ADMIN_MICROSOFT_ENABLED: 'mfa.admin.microsoft_enabled',
+    STOREFRONT_GOOGLE_ENABLED: 'mfa.storefront.google_enabled',
+    STOREFRONT_MICROSOFT_ENABLED: 'mfa.storefront.microsoft_enabled',
+};
+// ---------------------------------------------------------------------------
+// Ports
+// ---------------------------------------------------------------------------
+/** How many subjects hold an active second factor, split by identity store. */
+export const mfaActiveEnrolmentCountsSchema = z.object({
+    admins: z.number().int().nonnegative(),
+    customers: z.number().int().nonnegative(),
+});
+//# sourceMappingURL=mfa.js.map

package/dist/mfa.js.map

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