@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/identity/metadata/identity-metadata.service.js

@@ -0,0 +1,273 @@
+"use strict";
+// =============================================================================
+// IdentityMetadataService: the repository helpers over users.metadata and
+// organizations.metadata (PP-14.27)
+// =============================================================================
+//
+// Every method validates against the REGISTERED namespace schema, on the way
+// in and on the way out, and writes one namespace at a time:
+//
+//   - a write is a read-modify-write under `SELECT ... FOR UPDATE` in one
+//     transaction, so two writers of different namespaces never lose an update;
+//   - the whole document stays at most 16 KiB of compact JSON (the column's
+//     CHECK is a 32 KiB backstop, see the migration);
+//   - an object key named like a secret is refused, wherever it sits;
+//   - the document is never returned whole: a caller names a namespace.
+//
+// The helpers decide nothing about WHO may read or write: authorisation is the
+// calling route's, exactly as for any other service. `users` and
+// `organizations` have no row-level security, so the platform client is used as is.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityMetadataService = exports.MetadataError = exports.METADATA_MAX_BYTES = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../../core/index");
+const metadata_registry_1 = require("./metadata-registry");
+const metadata_secret_guard_1 = require("./metadata-secret-guard");
+/**
+ * The most a row's whole metadata document may hold, in bytes of compact JSON
+ * (`JSON.stringify`). The database CHECK allows twice this as a backstop.
+ *
+ * @stability experimental
+ */
+exports.METADATA_MAX_BYTES = 16 * 1024;
+/**
+ * The error every metadata operation throws.
+ *
+ * @stability experimental
+ */
+class MetadataError extends Error {
+    /** Machine-readable reason; see {@link MetadataErrorCode}. */
+    code;
+    /**
+     * @param code - Why the operation was refused.
+     * @param message - What is wrong and how to fix it.
+     * @param options - The underlying error, when there is one.
+     */
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'MetadataError';
+        this.code = code;
+    }
+}
+exports.MetadataError = MetadataError;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Locks the subject's row and returns its document; `undefined` when there is no such row. */
+async function lockDocument(tx, subject, id) {
+    const rows = subject === 'user'
+        ? await tx.$queryRaw `SELECT "metadata" FROM "users" WHERE "id" = ${id}::uuid FOR UPDATE`
+        : await tx.$queryRaw `SELECT "metadata" FROM "organizations" WHERE "id" = ${id}::uuid FOR UPDATE`;
+    return rows[0]?.metadata;
+}
+async function writeDocument(tx, subject, id, document) {
+    const json = JSON.stringify(document);
+    if (subject === 'user')
+        await tx.$executeRaw `UPDATE "users" SET "metadata" = ${json}::jsonb WHERE "id" = ${id}::uuid`;
+    else
+        await tx.$executeRaw `UPDATE "organizations" SET "metadata" = ${json}::jsonb WHERE "id" = ${id}::uuid`;
+}
+/**
+ * Reads and writes the namespaced metadata of users and organizations. Inject
+ * it anywhere (`IdentityModule` is global).
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class CoachPreferencesService {
+ *   constructor(private readonly metadata: IdentityMetadataService) {}
+ *   get(userId: string) { return this.metadata.getUserMetadata(userId, coachPreferences); }
+ * }
+ * ```
+ *
+ * @stability experimental
+ */
+let IdentityMetadataService = class IdentityMetadataService {
+    prisma;
+    /** @param prisma - The app's client, from the core port `PLATFORM_PRISMA`. */
+    constructor(prisma) {
+        this.prisma = prisma;
+    }
+    /**
+     * The value of one namespace of a user's metadata.
+     *
+     * @param userId - The user's id.
+     * @param namespace - A registered namespace, or the handle `registerUserMetadataSchema` returned (which types the result).
+     * @returns The validated value, or `undefined` when the user has none under it.
+     * @throws MetadataError `UNKNOWN_NAMESPACE`, `SUBJECT_NOT_FOUND`, `STORED_VALUE_INVALID`.
+     */
+    getUserMetadata(userId, namespace) {
+        return this.read('user', userId, namespace);
+    }
+    /**
+     * Replaces one namespace of a user's metadata.
+     *
+     * @param userId - The user's id.
+     * @param namespace - A registered namespace or its handle.
+     * @param value - The new value; validated against the namespace's schema.
+     * @returns The stored value (the schema's output, so transforms and stripping apply).
+     * @throws MetadataError `UNKNOWN_NAMESPACE`, `INVALID_VALUE`, `SECRET_KEY`, `TOO_LARGE`, `SUBJECT_NOT_FOUND`.
+     */
+    setUserMetadata(userId, namespace, value) {
+        return this.write('user', userId, namespace, () => value);
+    }
+    /**
+     * Changes one namespace of a user's metadata from its current value, under a
+     * row lock: the read and the write are one step.
+     *
+     * @param userId - The user's id.
+     * @param namespace - A registered namespace or its handle.
+     * @param change - Receives the current value (`undefined` when none) and returns the new one.
+     * @returns The stored value.
+     * @throws MetadataError as {@link IdentityMetadataService.setUserMetadata}, plus `STORED_VALUE_INVALID`.
+     */
+    updateUserMetadata(userId, namespace, change) {
+        return this.write('user', userId, namespace, change);
+    }
+    /**
+     * Removes one namespace from a user's metadata. A no-op when it is absent.
+     *
+     * @param userId - The user's id.
+     * @param namespace - A registered namespace or its handle.
+     * @throws MetadataError `UNKNOWN_NAMESPACE`, `SUBJECT_NOT_FOUND`.
+     */
+    deleteUserMetadata(userId, namespace) {
+        return this.remove('user', userId, namespace);
+    }
+    /**
+     * The value of one namespace of an organization's metadata.
+     *
+     * @param orgId - The organization's id.
+     * @param namespace - A registered namespace, or the handle `registerOrganizationMetadataSchema` returned.
+     * @returns The validated value, or `undefined` when the organization has none under it.
+     * @throws MetadataError `UNKNOWN_NAMESPACE`, `SUBJECT_NOT_FOUND`, `STORED_VALUE_INVALID`.
+     */
+    getOrganizationMetadata(orgId, namespace) {
+        return this.read('organization', orgId, namespace);
+    }
+    /**
+     * Replaces one namespace of an organization's metadata.
+     *
+     * @param orgId - The organization's id.
+     * @param namespace - A registered namespace or its handle.
+     * @param value - The new value; validated against the namespace's schema.
+     * @returns The stored value.
+     * @throws MetadataError `UNKNOWN_NAMESPACE`, `INVALID_VALUE`, `SECRET_KEY`, `TOO_LARGE`, `SUBJECT_NOT_FOUND`.
+     */
+    setOrganizationMetadata(orgId, namespace, value) {
+        return this.write('organization', orgId, namespace, () => value);
+    }
+    /**
+     * Changes one namespace of an organization's metadata from its current
+     * value, under a row lock.
+     *
+     * @param orgId - The organization's id.
+     * @param namespace - A registered namespace or its handle.
+     * @param change - Receives the current value (`undefined` when none) and returns the new one.
+     * @returns The stored value.
+     * @throws MetadataError as {@link IdentityMetadataService.setOrganizationMetadata}, plus `STORED_VALUE_INVALID`.
+     */
+    updateOrganizationMetadata(orgId, namespace, change) {
+        return this.write('organization', orgId, namespace, change);
+    }
+    /**
+     * Removes one namespace from an organization's metadata. A no-op when it is absent.
+     *
+     * @param orgId - The organization's id.
+     * @param namespace - A registered namespace or its handle.
+     * @throws MetadataError `UNKNOWN_NAMESPACE`, `SUBJECT_NOT_FOUND`.
+     */
+    deleteOrganizationMetadata(orgId, namespace) {
+        return this.remove('organization', orgId, namespace);
+    }
+    // ---- internals ------------------------------------------------------------------------
+    definition(subject, namespace) {
+        const name = typeof namespace === 'string' ? namespace : namespace.namespace;
+        const registry = subject === 'user' ? metadata_registry_1.userMetadataRegistry : metadata_registry_1.organizationMetadataRegistry;
+        const found = registry.get(name);
+        const register = subject === 'user' ? 'registerUserMetadataSchema' : 'registerOrganizationMetadataSchema';
+        if (!found || (typeof namespace !== 'string' && namespace.subject !== subject)) {
+            throw new MetadataError('UNKNOWN_NAMESPACE', `no ${subject} metadata namespace "${name}" is registered; call ${register}({ namespace, schema }) at import time`);
+        }
+        return found;
+    }
+    assertId(subject, id) {
+        if (typeof id !== 'string' || !UUID.test(id))
+            throw new MetadataError('SUBJECT_NOT_FOUND', `no ${subject} with id "${String(id)}"`);
+    }
+    parseStored(def, stored) {
+        const parsed = def.schema.safeParse(stored);
+        if (!parsed.success) {
+            throw new MetadataError('STORED_VALUE_INVALID', `the stored value of metadata namespace "${def.namespace}" no longer satisfies its schema (${parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ')}); migrate the data when the schema changes`, { cause: parsed.error });
+        }
+        return parsed.data;
+    }
+    async read(subject, id, namespace) {
+        const def = this.definition(subject, namespace);
+        this.assertId(subject, id);
+        const rows = subject === 'user'
+            ? await this.prisma.$queryRaw `SELECT "metadata" -> ${def.namespace}::text AS "value" FROM "users" WHERE "id" = ${id}::uuid`
+            : await this.prisma.$queryRaw `SELECT "metadata" -> ${def.namespace}::text AS "value" FROM "organizations" WHERE "id" = ${id}::uuid`;
+        if (rows.length === 0)
+            throw new MetadataError('SUBJECT_NOT_FOUND', `no ${subject} with id "${id}"`);
+        const stored = rows[0].value;
+        return stored === null || stored === undefined ? undefined : this.parseStored(def, stored);
+    }
+    async write(subject, id, namespace, change) {
+        const def = this.definition(subject, namespace);
+        this.assertId(subject, id);
+        return this.prisma.$transaction(async (tx) => {
+            const document = await lockDocument(tx, subject, id);
+            if (document === undefined)
+                throw new MetadataError('SUBJECT_NOT_FOUND', `no ${subject} with id "${id}"`);
+            const current = document[def.namespace];
+            const next = change(current === undefined || current === null ? undefined : this.parseStored(def, current));
+            const parsed = def.schema.safeParse(next);
+            if (!parsed.success) {
+                throw new MetadataError('INVALID_VALUE', `the value for metadata namespace "${def.namespace}" is invalid: ${parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ')}`, { cause: parsed.error });
+            }
+            const secrets = (0, metadata_secret_guard_1.findSecretKeys)(parsed.data);
+            if (secrets.length > 0) {
+                throw new MetadataError('SECRET_KEY', `metadata is not a secret store: the value for "${def.namespace}" holds secret-named key(s) ${secrets.join(', ')}; keep secrets in the encrypted credential store`);
+            }
+            const merged = { ...document, [def.namespace]: parsed.data };
+            const size = Buffer.byteLength(JSON.stringify(merged), 'utf8');
+            if (size > exports.METADATA_MAX_BYTES) {
+                throw new MetadataError('TOO_LARGE', `the ${subject} metadata document would be ${size} bytes, over the ${exports.METADATA_MAX_BYTES} byte limit; keep large data in its own table`);
+            }
+            await writeDocument(tx, subject, id, merged);
+            return parsed.data;
+        });
+    }
+    async remove(subject, id, namespace) {
+        const def = this.definition(subject, namespace);
+        this.assertId(subject, id);
+        await this.prisma.$transaction(async (tx) => {
+            const document = await lockDocument(tx, subject, id);
+            if (document === undefined)
+                throw new MetadataError('SUBJECT_NOT_FOUND', `no ${subject} with id "${id}"`);
+            if (!(def.namespace in document))
+                return;
+            const { [def.namespace]: _removed, ...rest } = document;
+            await writeDocument(tx, subject, id, rest);
+        });
+    }
+};
+exports.IdentityMetadataService = IdentityMetadataService;
+exports.IdentityMetadataService = IdentityMetadataService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(index_1.PLATFORM_PRISMA)),
+    __metadata("design:paramtypes", [Object])
+], IdentityMetadataService);
+//# sourceMappingURL=identity-metadata.service.js.map

package/dist/identity/metadata/identity-metadata.service.js.map

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

package/dist/identity/metadata/metadata-registry.d.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { type Registry } from '../../core/index';
+/**
+ * Which row a metadata document lives on.
+ *
+ * @stability experimental
+ */
+export type MetadataSubject = 'user' | 'organization';
+/**
+ * A namespace's declaration: the key under which an app keeps its fields, and
+ * the zod schema that validates them.
+ *
+ * @stability experimental
+ */
+export interface MetadataNamespaceDef<T = unknown> {
+    /**
+     * The JSON key. Lower-case words joined by `.`, `-` or `_` (`preferences.coach`), at most 63 characters. Permanent once rows hold it. Namespaces of one app should share a prefix it owns, so two packages never collide.
+     */
+    readonly namespace: string;
+    /**
+     * The shape of the value. A closed object schema: no `z.any()`, `z.unknown()` or loose object anywhere, and no property named like a secret (`password`, `apiKey`, `token`, `webhookSecret`, ...). Secrets go in the encrypted credential store, never here.
+     */
+    readonly schema: z.ZodType<T>;
+    /** One line for the Doctor and the docs: what the namespace is for. */
+    readonly description?: string;
+}
+/**
+ * The typed handle a registration returns; pass it to the service's methods and
+ * the value type follows from the schema.
+ *
+ * @stability experimental
+ */
+export interface MetadataNamespace<T = unknown> extends MetadataNamespaceDef<T> {
+    /** The row kind the namespace belongs to. */
+    readonly subject: MetadataSubject;
+}
+/**
+ * The namespace pattern: lower-case words joined by `.`, `-` or `_`.
+ *
+ * @stability experimental
+ */
+export declare const METADATA_NAMESPACE_PATTERN: RegExp;
+/**
+ * Every registered `users.metadata` namespace. Read it; register with
+ * {@link registerUserMetadataSchema}.
+ *
+ * @stability experimental
+ */
+export declare const userMetadataRegistry: Registry<MetadataNamespaceDef>;
+/**
+ * Every registered `organizations.metadata` namespace. Read it; register with
+ * {@link registerOrganizationMetadataSchema}.
+ *
+ * @stability experimental
+ */
+export declare const organizationMetadataRegistry: Registry<MetadataNamespaceDef>;
+/**
+ * Declares a namespace of `users.metadata` and returns its typed handle. Call
+ * it at import time, before the application bootstraps.
+ *
+ * The schema is validated now (closed object, no secret-named field) and on
+ * every write and read. The platform exposes no route over the document: an
+ * app that wants a namespace over HTTP writes the route (or contributes to the
+ * current-user response) and returns what it chooses.
+ *
+ * @param def - The namespace and its schema.
+ * @returns The handle, `{ subject: 'user', namespace, schema }`.
+ * @throws RegistryError `INVALID_ID` for a malformed namespace, `INVALID_ENTRY` for a schema that is not a closed object schema or declares a secret-named field, `DUPLICATE_ID` for a namespace already registered, `FROZEN` after bootstrap.
+ *
+ * @example
+ * ```ts
+ * export const coachPreferences = registerUserMetadataSchema({
+ *   namespace: 'preferences.coach',
+ *   schema: z.object({ reminderHour: z.number().int().min(0).max(23), weeklyDigest: z.boolean() }),
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerUserMetadataSchema<T>(def: MetadataNamespaceDef<T>): MetadataNamespace<T>;
+/**
+ * Declares a namespace of `organizations.metadata` and returns its typed
+ * handle; the same contract as {@link registerUserMetadataSchema}.
+ *
+ * @param def - The namespace and its schema.
+ * @returns The handle, `{ subject: 'organization', namespace, schema }`.
+ * @throws RegistryError as {@link registerUserMetadataSchema}.
+ *
+ * @example
+ * ```ts
+ * export const coachProgram = registerOrganizationMetadataSchema({
+ *   namespace: 'program.coach',
+ *   schema: z.object({ seats: z.number().int().positive() }),
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerOrganizationMetadataSchema<T>(def: MetadataNamespaceDef<T>): MetadataNamespace<T>;
+//# sourceMappingURL=metadata-registry.d.ts.map

package/dist/identity/metadata/metadata-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-registry.d.ts","sourceRoot":"","sources":["../../../src/identity/metadata/metadata-registry.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGjE;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,cAAc,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC/C;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,oBAAoB,CAAC,CAAC,CAAC;IAC7E,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,QAAwC,CAAC;AAwChF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,oBAAoB,CAAwB,CAAC;AAEzF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CAAC,oBAAoB,CAAgC,CAAC;AAEzG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,GAAG,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAGhG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kCAAkC,CAAC,CAAC,EAAE,GAAG,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAGxG"}

package/dist/identity/metadata/metadata-registry.js

@@ -0,0 +1,130 @@
+"use strict";
+// =============================================================================
+// Metadata namespace registries (PP-14.27)
+// =============================================================================
+//
+// `users.metadata` and `organizations.metadata` hold one top-level key per
+// REGISTERED namespace; the value under it is validated against that
+// namespace's zod schema on every write and every read. Two static registries on
+// the #675 primitive (`defineRegistry`): a duplicate namespace throws at import,
+// and the registry freezes once the application has bootstrapped, so an app
+// registers at import time from `app-registrations/identity.ts`, never from
+// `onModuleInit`.
+//
+// A namespace is PERMANENT once rows hold it (it is the JSON key), like a job
+// type or a settings key: renaming one strands every stored value.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.organizationMetadataRegistry = exports.userMetadataRegistry = exports.METADATA_NAMESPACE_PATTERN = void 0;
+exports.registerUserMetadataSchema = registerUserMetadataSchema;
+exports.registerOrganizationMetadataSchema = registerOrganizationMetadataSchema;
+const zod_1 = require("zod");
+const index_1 = require("../../core/index");
+const metadata_secret_guard_1 = require("./metadata-secret-guard");
+/**
+ * The namespace pattern: lower-case words joined by `.`, `-` or `_`.
+ *
+ * @stability experimental
+ */
+exports.METADATA_NAMESPACE_PATTERN = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const NAMESPACE_MAX_LENGTH = 63;
+function validateDef(subject) {
+    const register = subject === 'user' ? 'registerUserMetadataSchema' : 'registerOrganizationMetadataSchema';
+    return (def) => {
+        if (typeof def.namespace !== 'string' || def.namespace.length > NAMESPACE_MAX_LENGTH) {
+            throw new Error(`namespace must be at most ${NAMESPACE_MAX_LENGTH} characters`);
+        }
+        if (!(def.schema instanceof zod_1.z.ZodType))
+            throw new Error(`${register}: schema must be a zod schema`);
+        let findings;
+        try {
+            findings = (0, metadata_secret_guard_1.inspectMetadataSchema)(def.schema);
+        }
+        catch (error) {
+            throw new Error(`schema cannot be introspected (${error.message}); use a plain object schema without z.lazy`);
+        }
+        if (findings.rootNotObject)
+            throw new Error('schema must be an object schema (z.object({ ... })): a namespace holds named fields');
+        if (findings.secretFields.length > 0) {
+            throw new Error(`schema declares secret-named field(s) ${findings.secretFields.join(', ')}; metadata is not a secret store: keep the secret in the encrypted credential store (user_credentials / credentials) and, at most, a "hasKey" flag here`);
+        }
+        if (findings.openShapes.length > 0) {
+            throw new Error(`schema leaves part of its shape open (${findings.openShapes.join(', ')}); declare every field so the namespace can be reviewed (no z.any(), z.unknown(), z.date() or loose objects)`);
+        }
+    };
+}
+function makeRegistry(subject) {
+    return (0, index_1.defineRegistry)({
+        name: subject === 'user' ? 'user-metadata-schemas' : 'organization-metadata-schemas',
+        idOf: (def) => def.namespace,
+        idPattern: exports.METADATA_NAMESPACE_PATTERN,
+        validate: validateDef(subject),
+        describeDuplicate: (existing, incoming) => `${subject} metadata namespace "${incoming.namespace}" is already registered${existing.description ? ` (${existing.description})` : ''}; choose another namespace, prefixed with the owner.`,
+    });
+}
+/**
+ * Every registered `users.metadata` namespace. Read it; register with
+ * {@link registerUserMetadataSchema}.
+ *
+ * @stability experimental
+ */
+exports.userMetadataRegistry = makeRegistry('user');
+/**
+ * Every registered `organizations.metadata` namespace. Read it; register with
+ * {@link registerOrganizationMetadataSchema}.
+ *
+ * @stability experimental
+ */
+exports.organizationMetadataRegistry = makeRegistry('organization');
+/**
+ * Declares a namespace of `users.metadata` and returns its typed handle. Call
+ * it at import time, before the application bootstraps.
+ *
+ * The schema is validated now (closed object, no secret-named field) and on
+ * every write and read. The platform exposes no route over the document: an
+ * app that wants a namespace over HTTP writes the route (or contributes to the
+ * current-user response) and returns what it chooses.
+ *
+ * @param def - The namespace and its schema.
+ * @returns The handle, `{ subject: 'user', namespace, schema }`.
+ * @throws RegistryError `INVALID_ID` for a malformed namespace, `INVALID_ENTRY` for a schema that is not a closed object schema or declares a secret-named field, `DUPLICATE_ID` for a namespace already registered, `FROZEN` after bootstrap.
+ *
+ * @example
+ * ```ts
+ * export const coachPreferences = registerUserMetadataSchema({
+ *   namespace: 'preferences.coach',
+ *   schema: z.object({ reminderHour: z.number().int().min(0).max(23), weeklyDigest: z.boolean() }),
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+function registerUserMetadataSchema(def) {
+    exports.userMetadataRegistry.register(def);
+    return { ...def, subject: 'user' };
+}
+/**
+ * Declares a namespace of `organizations.metadata` and returns its typed
+ * handle; the same contract as {@link registerUserMetadataSchema}.
+ *
+ * @param def - The namespace and its schema.
+ * @returns The handle, `{ subject: 'organization', namespace, schema }`.
+ * @throws RegistryError as {@link registerUserMetadataSchema}.
+ *
+ * @example
+ * ```ts
+ * export const coachProgram = registerOrganizationMetadataSchema({
+ *   namespace: 'program.coach',
+ *   schema: z.object({ seats: z.number().int().positive() }),
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+function registerOrganizationMetadataSchema(def) {
+    exports.organizationMetadataRegistry.register(def);
+    return { ...def, subject: 'organization' };
+}
+//# sourceMappingURL=metadata-registry.js.map

package/dist/identity/metadata/metadata-registry.js.map

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

package/dist/identity/metadata/metadata-secret-guard.d.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+/**
+ * Field names that mark a metadata value as a secret, compared
+ * case-insensitively with `_`, `-` and `.` ignored: the settings deny-list
+ * (`secretAccessKey`, `secretKey`, `sessionToken`, `secret`, `password`,
+ * `apiKey`, `token`, `privateKey`) plus `accessToken`, `refreshToken`,
+ * `authToken`, `bearer`, `authorization`, `credential`, `credentials`,
+ * `passphrase`, `clientSecret` and `signingKey`. A name that merely ends in
+ * `secret`, `password`, `passphrase`, `apikey`, `privatekey`, `secretkey`,
+ * `signingkey` or `token` after one of those words is refused too
+ * (`webhookSecret`, `stripeApiKey`).
+ *
+ * @stability experimental
+ */
+export declare const METADATA_SECRET_FIELD_NAMES: readonly ["secretAccessKey", "secretKey", "sessionToken", "secret", "password", "apiKey", "token", "privateKey", "accessToken", "refreshToken", "authToken", "bearer", "authorization", "credential", "credentials", "passphrase", "clientSecret", "signingKey"];
+/**
+ * Whether a field name reads as a secret (see {@link METADATA_SECRET_FIELD_NAMES}).
+ *
+ * @param name - An object key or schema property name.
+ * @returns True when the name is one of the deny-list or ends in one of its suffixes.
+ * @stability experimental
+ */
+export declare function isSecretFieldName(name: string): boolean;
+/**
+ * What the registration walk found wrong in a schema.
+ *
+ * @stability experimental
+ */
+export interface MetadataSchemaFindings {
+    /** Property paths whose name reads as a secret. */
+    secretFields: string[];
+    /** Paths whose shape is left open (`z.any()`, `z.unknown()`, `z.date()`, a loose object). */
+    openShapes: string[];
+    /** True when the root is not an object schema. */
+    rootNotObject: boolean;
+}
+/**
+ * Walks a zod schema (as its input JSON Schema) for secret-named properties
+ * and open shapes.
+ *
+ * @param schema - A zod schema.
+ * @returns The findings; all empty when the schema is acceptable.
+ * @throws Error when the schema cannot be introspected (for example a recursive `z.lazy`).
+ * @stability experimental
+ */
+export declare function inspectMetadataSchema(schema: z.ZodType): MetadataSchemaFindings;
+/**
+ * Every object key in a value, at any depth, that reads as a secret. The write
+ * side of the guard: it sees the keys of a `z.record`, which the schema walk
+ * cannot.
+ *
+ * @param value - A JSON value.
+ * @param path - The path of `value` (internal).
+ * @returns The dotted paths of offending keys; empty when none.
+ * @stability experimental
+ */
+export declare function findSecretKeys(value: unknown, path?: string): string[];
+//# sourceMappingURL=metadata-secret-guard.d.ts.map

package/dist/identity/metadata/metadata-secret-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-secret-guard.d.ts","sourceRoot":"","sources":["../../../src/identity/metadata/metadata-secret-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,kQAmB9B,CAAC;AASX;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGvD;AAcD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,mDAAmD;IACnD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,6FAA6F;IAC7F,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,kDAAkD;IAClD,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,sBAAsB,CAsB/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAK,GAAG,MAAM,EAAE,CAOlE"}