@aooth/auth 0.1.19 → 0.1.21

package/dist/atscript-db.cjs

@@ -233,13 +233,15 @@ function rowToDynamicClient(row) {
 */
 var CredentialStoreAtscriptDb = class {
 	table;
+	metadataField;
 	constructor(opts) {
 		this.table = opts.table;
+		this.metadataField = opts.metadataField;
 	}
 	async persist(state, ttl) {
 		const token = (0, node_crypto.randomUUID)();
 		const expiresAt = typeof ttl === "number" ? Date.now() + ttl : state.expiresAt;
-		await this.table.insertOne(stateToRow(state, token, expiresAt));
+		await this.table.insertOne(stateToRow(state, token, expiresAt, this.metadataField));
 		return token;
 	}
 	async retrieve(token) {
@@ -249,7 +251,7 @@ var CredentialStoreAtscriptDb = class {
 			await this.table.deleteOne(token).catch(() => {});
 			return null;
 		}
-		return rowToState(row);
+		return rowToState(row, this.metadataField);
 	}
 	async consume(token) {
 		const state = await this.retrieve(token);
@@ -263,7 +265,7 @@ var CredentialStoreAtscriptDb = class {
 			await this.revoke(token);
 			return token;
 		}
-		await this.table.replaceOne(stateToRow(state, token, state.expiresAt));
+		await this.table.replaceOne(stateToRow(state, token, state.expiresAt, this.metadataField));
 		return token;
 	}
 	async revoke(token) {
@@ -292,7 +294,7 @@ var CredentialStoreAtscriptDb = class {
 				continue;
 			}
 			out.push({
-				...rowToState(row),
+				...rowToState(row, this.metadataField),
 				token: row.token
 			});
 		}
@@ -305,30 +307,45 @@ var CredentialStoreAtscriptDb = class {
 * (so an envelope field wins a name clash), then the fixed envelope fields and
 * the resolved `token` + `expiresAt`. Shared by `persist` and `update`, which
 * differ only in the `expiresAt` they resolve.
+*
+* The envelope's `metadata` is written to the consumer's `metadataField`
+* column (a dynamic key the static row type can't carry) — only when the
+* field is configured; otherwise metadata is silently not persisted.
 */
-function stateToRow(state, token, expiresAt) {
-	return {
+function stateToRow(state, token, expiresAt, metadataField) {
+	const row = {
 		...require_payload.credentialPayloadOf(state),
 		token,
 		userId: state.userId,
 		issuedAt: state.issuedAt,
 		expiresAt,
 		kind: state.kind,
-		metadata: state.metadata,
 		parentCredentialId: state.parentCredentialId,
 		rotatedAt: state.rotatedAt,
 		sessionId: state.sessionId,
 		lastSeenAt: state.lastSeenAt
 	};
+	if (metadataField !== void 0 && state.metadata !== void 0) row[metadataField] = state.metadata;
+	return row;
 }
-function rowToState(row) {
+/**
+* Inverse of {@link stateToRow}. The consumer's `metadataField` column maps
+* back onto the envelope's `metadata` — and is excluded from the extracted
+* payload (it is envelope data riding under a consumer-chosen name, not a
+* typed payload field).
+*/
+function rowToState(row, metadataField) {
 	const state = {
 		...require_payload.credentialPayloadOf(row),
 		userId: row.userId,
 		issuedAt: row.issuedAt,
 		expiresAt: row.expiresAt
 	};
-	if (row.metadata !== void 0) state.metadata = row.metadata;
+	if (metadataField !== void 0) {
+		delete state[metadataField];
+		const metadata = row[metadataField];
+		if (metadata !== void 0) state.metadata = metadata;
+	}
 	if (row.kind === "access" || row.kind === "refresh") state.kind = row.kind;
 	if (row.parentCredentialId !== void 0) state.parentCredentialId = row.parentCredentialId;
 	if (row.rotatedAt !== void 0) state.rotatedAt = row.rotatedAt;

package/dist/atscript-db.d.cts

@@ -210,6 +210,11 @@ declare class DynamicClientStoreAtscriptDb extends DynamicClientStore {
  * The consumer's typed payload `TPayload` (the root fields they add to their
  * `extends AoothAuthCredential` model) is intersected flat — those become real
  * typed columns, replacing the dropped free-form `claims` blob.
+ *
+ * There is NO `metadata` envelope column: credential metadata is
+ * consumer-declared (a fully-typed `@db.json` field on the extending model,
+ * marked `@aooth.auth.metadata`) and mapped dynamically through the
+ * `metadataField` option below.
  */
 type AuthCredentialRow<TPayload extends object = object> = {
   token: string;
@@ -217,12 +222,6 @@ type AuthCredentialRow<TPayload extends object = object> = {
   issuedAt: number;
   expiresAt: number;
   kind?: string;
-  metadata?: {
-    ip?: string;
-    userAgent?: string;
-    fingerprint?: string;
-    label?: string;
-  };
   parentCredentialId?: string;
   rotatedAt?: number;
   sessionId?: string;
@@ -258,6 +257,15 @@ interface AuthCredentialTable<TPayload extends object = object> {
 }
 interface CredentialStoreAtscriptDbOptions<TPayload extends object> {
   table: AuthCredentialTable<TPayload>;
+  /**
+   * Name of the consumer's `@aooth.auth.metadata`-annotated column — the
+   * fully-typed `@db.json` field declared on their `extends AoothAuthCredential`
+   * model that persists the envelope's `metadata`. Resolved at boot by
+   * `getAoothCredentialMetadataSpec` (`@aooth/arbac-moost/atscript`) and
+   * threaded here as plain config — same pattern as `UserStore.handleFields`.
+   * Absent → metadata is not persisted/read by this store.
+   */
+  metadataField?: string;
 }
 /**
  * atscript-db-backed `CredentialStore`.
@@ -274,6 +282,7 @@ interface CredentialStoreAtscriptDbOptions<TPayload extends object> {
  */
 declare class CredentialStoreAtscriptDb<TPayload extends object = object> implements CredentialStore<TPayload> {
   private readonly table;
+  private readonly metadataField;
   constructor(opts: CredentialStoreAtscriptDbOptions<TPayload>);
   persist(state: CredentialState & TPayload, ttl?: number): Promise<string>;
   retrieve(token: string): Promise<(CredentialState & TPayload) | null>;

package/dist/atscript-db.d.mts

@@ -210,6 +210,11 @@ declare class DynamicClientStoreAtscriptDb extends DynamicClientStore {
  * The consumer's typed payload `TPayload` (the root fields they add to their
  * `extends AoothAuthCredential` model) is intersected flat — those become real
  * typed columns, replacing the dropped free-form `claims` blob.
+ *
+ * There is NO `metadata` envelope column: credential metadata is
+ * consumer-declared (a fully-typed `@db.json` field on the extending model,
+ * marked `@aooth.auth.metadata`) and mapped dynamically through the
+ * `metadataField` option below.
  */
 type AuthCredentialRow<TPayload extends object = object> = {
   token: string;
@@ -217,12 +222,6 @@ type AuthCredentialRow<TPayload extends object = object> = {
   issuedAt: number;
   expiresAt: number;
   kind?: string;
-  metadata?: {
-    ip?: string;
-    userAgent?: string;
-    fingerprint?: string;
-    label?: string;
-  };
   parentCredentialId?: string;
   rotatedAt?: number;
   sessionId?: string;
@@ -258,6 +257,15 @@ interface AuthCredentialTable<TPayload extends object = object> {
 }
 interface CredentialStoreAtscriptDbOptions<TPayload extends object> {
   table: AuthCredentialTable<TPayload>;
+  /**
+   * Name of the consumer's `@aooth.auth.metadata`-annotated column — the
+   * fully-typed `@db.json` field declared on their `extends AoothAuthCredential`
+   * model that persists the envelope's `metadata`. Resolved at boot by
+   * `getAoothCredentialMetadataSpec` (`@aooth/arbac-moost/atscript`) and
+   * threaded here as plain config — same pattern as `UserStore.handleFields`.
+   * Absent → metadata is not persisted/read by this store.
+   */
+  metadataField?: string;
 }
 /**
  * atscript-db-backed `CredentialStore`.
@@ -274,6 +282,7 @@ interface CredentialStoreAtscriptDbOptions<TPayload extends object> {
  */
 declare class CredentialStoreAtscriptDb<TPayload extends object = object> implements CredentialStore<TPayload> {
   private readonly table;
+  private readonly metadataField;
   constructor(opts: CredentialStoreAtscriptDbOptions<TPayload>);
   persist(state: CredentialState & TPayload, ttl?: number): Promise<string>;
   retrieve(token: string): Promise<(CredentialState & TPayload) | null>;

package/dist/atscript-db.mjs

@@ -232,13 +232,15 @@ function rowToDynamicClient(row) {
 */
 var CredentialStoreAtscriptDb = class {
 	table;
+	metadataField;
 	constructor(opts) {
 		this.table = opts.table;
+		this.metadataField = opts.metadataField;
 	}
 	async persist(state, ttl) {
 		const token = randomUUID();
 		const expiresAt = typeof ttl === "number" ? Date.now() + ttl : state.expiresAt;
-		await this.table.insertOne(stateToRow(state, token, expiresAt));
+		await this.table.insertOne(stateToRow(state, token, expiresAt, this.metadataField));
 		return token;
 	}
 	async retrieve(token) {
@@ -248,7 +250,7 @@ var CredentialStoreAtscriptDb = class {
 			await this.table.deleteOne(token).catch(() => {});
 			return null;
 		}
-		return rowToState(row);
+		return rowToState(row, this.metadataField);
 	}
 	async consume(token) {
 		const state = await this.retrieve(token);
@@ -262,7 +264,7 @@ var CredentialStoreAtscriptDb = class {
 			await this.revoke(token);
 			return token;
 		}
-		await this.table.replaceOne(stateToRow(state, token, state.expiresAt));
+		await this.table.replaceOne(stateToRow(state, token, state.expiresAt, this.metadataField));
 		return token;
 	}
 	async revoke(token) {
@@ -291,7 +293,7 @@ var CredentialStoreAtscriptDb = class {
 				continue;
 			}
 			out.push({
-				...rowToState(row),
+				...rowToState(row, this.metadataField),
 				token: row.token
 			});
 		}
@@ -304,30 +306,45 @@ var CredentialStoreAtscriptDb = class {
 * (so an envelope field wins a name clash), then the fixed envelope fields and
 * the resolved `token` + `expiresAt`. Shared by `persist` and `update`, which
 * differ only in the `expiresAt` they resolve.
+*
+* The envelope's `metadata` is written to the consumer's `metadataField`
+* column (a dynamic key the static row type can't carry) — only when the
+* field is configured; otherwise metadata is silently not persisted.
 */
-function stateToRow(state, token, expiresAt) {
-	return {
+function stateToRow(state, token, expiresAt, metadataField) {
+	const row = {
 		...credentialPayloadOf(state),
 		token,
 		userId: state.userId,
 		issuedAt: state.issuedAt,
 		expiresAt,
 		kind: state.kind,
-		metadata: state.metadata,
 		parentCredentialId: state.parentCredentialId,
 		rotatedAt: state.rotatedAt,
 		sessionId: state.sessionId,
 		lastSeenAt: state.lastSeenAt
 	};
+	if (metadataField !== void 0 && state.metadata !== void 0) row[metadataField] = state.metadata;
+	return row;
 }
-function rowToState(row) {
+/**
+* Inverse of {@link stateToRow}. The consumer's `metadataField` column maps
+* back onto the envelope's `metadata` — and is excluded from the extracted
+* payload (it is envelope data riding under a consumer-chosen name, not a
+* typed payload field).
+*/
+function rowToState(row, metadataField) {
 	const state = {
 		...credentialPayloadOf(row),
 		userId: row.userId,
 		issuedAt: row.issuedAt,
 		expiresAt: row.expiresAt
 	};
-	if (row.metadata !== void 0) state.metadata = row.metadata;
+	if (metadataField !== void 0) {
+		delete state[metadataField];
+		const metadata = row[metadataField];
+		if (metadata !== void 0) state.metadata = metadata;
+	}
 	if (row.kind === "access" || row.kind === "refresh") state.kind = row.kind;
 	if (row.parentCredentialId !== void 0) state.parentCredentialId = row.parentCredentialId;
 	if (row.rotatedAt !== void 0) state.rotatedAt = row.rotatedAt;

package/dist/index.d.cts

@@ -420,9 +420,11 @@ declare class AuthCredential<TPayload extends object = object> {
  *
  * `mfa.code` is reserved for v2 — v1 is TOTP only. `login.pincode`,
  * `recovery.pincode`, `invite.pincode` and `notifyNewDevice` are added with
- * BIG 3.1 (login workflow re-implementation).
+ * BIG 3.1 (login workflow re-implementation). `securityAlert` is the
+ * consumer-triggered security notice (e.g. impossible-travel from a
+ * `resolveRiskStepUp` override) — never auto-sent by the framework.
  */
-type AuthEmailKind = "recovery.magicLink" | "invite.magicLink" | "mfa.code" | "login.pincode" | "recovery.pincode" | "invite.pincode" | "notifyNewDevice";
+type AuthEmailKind = "recovery.magicLink" | "invite.magicLink" | "mfa.code" | "login.pincode" | "recovery.pincode" | "invite.pincode" | "notifyNewDevice" | "securityAlert";
 /**
  * Structured event passed to `EmailSender.send()` from inside the auth
  * workflows. Flat and serialisable so consumers can route it to any

package/dist/index.d.mts

@@ -420,9 +420,11 @@ declare class AuthCredential<TPayload extends object = object> {
  *
  * `mfa.code` is reserved for v2 — v1 is TOTP only. `login.pincode`,
  * `recovery.pincode`, `invite.pincode` and `notifyNewDevice` are added with
- * BIG 3.1 (login workflow re-implementation).
+ * BIG 3.1 (login workflow re-implementation). `securityAlert` is the
+ * consumer-triggered security notice (e.g. impossible-travel from a
+ * `resolveRiskStepUp` override) — never auto-sent by the framework.
  */
-type AuthEmailKind = "recovery.magicLink" | "invite.magicLink" | "mfa.code" | "login.pincode" | "recovery.pincode" | "invite.pincode" | "notifyNewDevice";
+type AuthEmailKind = "recovery.magicLink" | "invite.magicLink" | "mfa.code" | "login.pincode" | "recovery.pincode" | "invite.pincode" | "notifyNewDevice" | "securityAlert";
 /**
  * Structured event passed to `EmailSender.send()` from inside the auth
  * workflows. Flat and serialisable so consumers can route it to any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aooth/auth",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Auth method layer for aoothjs (sessions, tokens, password reset, MFA primitives)",
   "keywords": [
     "aoothjs",
@@ -104,17 +104,17 @@
   },
   "dependencies": {
     "jose": "^6.2.3",
-    "@aooth/user": "0.1.19"
+    "@aooth/user": "0.1.21"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.75",
-    "@atscript/db": "^0.1.104",
-    "@atscript/db-sql-tools": "^0.1.104",
-    "@atscript/db-sqlite": "^0.1.104",
-    "@atscript/typescript": "^0.1.75",
+    "@atscript/core": "^0.1.76",
+    "@atscript/db": "^0.1.106",
+    "@atscript/db-sql-tools": "^0.1.106",
+    "@atscript/db-sqlite": "^0.1.106",
+    "@atscript/typescript": "^0.1.76",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.6.2",
-    "unplugin-atscript": "^0.1.75"
+    "unplugin-atscript": "^0.1.76"
   },
   "peerDependencies": {
     "@atscript/db": ">=0.1.79"

package/src/atscript-db/auth-credential.as

@@ -1,3 +1,36 @@
+/**
+ * The framework-written credential-metadata envelope keys — the `.as` twin of
+ * `CredentialMetadata` in `@aooth/auth` (keep the two in sync). The bundled
+ * row model ships NO metadata column; a consumer who wants metadata persisted
+ * declares their own `@aooth.auth.metadata @db.json` field and builds its shape
+ * by INTERSECTING this type with their extension keys:
+ *
+ *     import { AoothAuthCredential, AoothCredentialMetadataBase } from '@aooth/auth/atscript-db/model'
+ *
+ *     @aooth.auth.metadata
+ *     @db.json
+ *     metadata?: AoothCredentialMetadataBase & { geoLat?: number, geoLon?: number }
+ *
+ * That keeps one source of truth for the framework keys: when a future aooth
+ * release adds an envelope key here, consumer schemas pick it up on upgrade
+ * instead of silently rejecting it from their hand-mirrored closed shape.
+ */
+export type AoothCredentialMetadataBase = {
+    /** Client IP captured at issue time (default `resolveIssueMetadata`). */
+    ip?: string
+    /** Raw User-Agent captured at issue time. */
+    userAgent?: string
+    /** Consumer-supplied device fingerprint (`IssueOptions.fingerprint`). */
+    fingerprint?: string
+    /** Human-readable session label. */
+    label?: string
+    /**
+     * Semantic credential kind (e.g. "cli-session" / "pat") — distinct from
+     * the internal access/refresh `kind` column on the row.
+     */
+    credentialKind?: string
+}
+
 @db.table 'aooth_credentials'
 @db.depth.limit 0
 export interface AoothAuthCredential {
@@ -23,20 +56,13 @@ export interface AoothAuthCredential {
      */
     kind?: string
 
-    /**
-     * Display metadata: ip, userAgent, fingerprint, label, plus the semantic
-     * credential kind (`cli-session` / `pat` / …) folded in by `issue()`. The
-     * `@db.json` column is schema-validated, so every field `CredentialMetadata`
-     * may carry must be declared here.
-     */
-    @db.json
-    metadata?: {
-        ip?: string
-        userAgent?: string
-        fingerprint?: string
-        label?: string
-        credentialKind?: string
-    }
+    // NO metadata column here — credential metadata is CONSUMER-DECLARED.
+    // Declare a fully-typed `@db.json` field on your extending model (the
+    // runtime/validation twin of your `CredentialMetadata` declaration merge)
+    // and mark it `@aooth.auth.metadata`; without one, the atscript-db store
+    // persists no metadata (memory/JWT stores are unaffected). Build the shape
+    // as `AoothCredentialMetadataBase & { ...your keys }` (exported above) so
+    // the framework-written keys stay single-sourced.
 
     /** Set by refresh-token rotation. */
     parentCredentialId?: string

package/src/atscript-db/auth-credential.as.d.ts

@@ -9,9 +9,31 @@
 
 import type { TAtscriptTypeObject, TAtscriptTypeComplex, TAtscriptTypeFinal, TAtscriptTypeArray, TAtscriptAnnotatedType, TMetadataMap, Validator, TValidatorOptions } from "@atscript/typescript/utils"
 
+/**
+ * Atscript type **AoothCredentialMetadataBase**
+ * @see {@link ./auth-credential.as:18:13}
+ */
+export type AoothCredentialMetadataBase = {
+  ip?: string
+  userAgent?: string
+  fingerprint?: string
+  label?: string
+  credentialKind?: string
+}
+declare namespace AoothCredentialMetadataBase {
+  const __is_atscript_annotated_type: true
+  const type: TAtscriptTypeObject<keyof AoothCredentialMetadataBase, AoothCredentialMetadataBase>
+  const metadata: TMetadataMap<AtscriptMetadata>
+  const validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof AoothCredentialMetadataBase>
+  /** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */
+  const toJsonSchema: () => any
+  /** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */
+  const toExampleData: (() => any) | undefined
+}
+
 /**
  * Atscript interface **AoothAuthCredential**
- * @see {@link ./auth-credential.as:3:18}
+ * @see {@link ./auth-credential.as:36:18}
  */
 export declare class AoothAuthCredential {
   token: string
@@ -19,13 +41,6 @@ export declare class AoothAuthCredential {
   issuedAt: number /* timestamp */
   expiresAt: number /* timestamp */
   kind?: string
-  metadata?: {
-    ip?: string
-    userAgent?: string
-    fingerprint?: string
-    label?: string
-    credentialKind?: string
-  }
   parentCredentialId?: string
   rotatedAt?: number /* timestamp */
   sessionId?: string
@@ -44,7 +59,6 @@ export declare class AoothAuthCredential {
     "issuedAt": number /* timestamp */
     "expiresAt": number /* timestamp */
     "kind"?: string
-    "metadata"?: string
     "parentCredentialId"?: string
     "rotatedAt"?: number /* timestamp */
     "sessionId"?: string
@@ -56,7 +70,6 @@ export declare class AoothAuthCredential {
     "issuedAt": number /* timestamp */
     "expiresAt": number /* timestamp */
     "kind"?: string
-    "metadata"?: string
     "parentCredentialId"?: string
     "rotatedAt"?: number /* timestamp */
     "sessionId"?: string