@things-factory/auth-base 10.1.31 → 10.1.34

package/dist-server/utils/credential-at-rest.d.ts

@@ -0,0 +1,28 @@
+import { ValueTransformer } from 'typeorm';
+/**
+ * A credential column that encrypts only where the installation asked for it (ADR-0085).
+ *
+ * ── The switch governs writing. Reading always takes both ───────────────────
+ * `shell`'s `encryptTransformer` reads a value that is not ciphertext-shaped as plaintext, so
+ * rows written before the switch was turned on stay readable, and each row converts the next
+ * time something writes it. That behaviour does **not** move with the switch — if it did,
+ * turning the feature off would lose every row written while it was on.
+ *
+ * So off means "write it the way we always did", not "pretend the encrypted rows are not
+ * there".
+ *
+ * ── The switch is read per write, not once at import ────────────────────────
+ * A module-level constant would freeze whatever the config looked like when the entity file was
+ * first loaded, which is not the same thing in tests and not obviously the same thing at boot.
+ * `to` asks each time; it is a property lookup.
+ *
+ * ── Where this is NOT used: `User.password` ─────────────────────────────────
+ * That column holds a different thing depending on who the row is. For a person it is an HMAC
+ * of their password — already not the secret, so encrypting it protects nothing. For an
+ * appliance or an app binding it is the token itself, which is exactly what this is for.
+ *
+ * A column transformer cannot tell those apart, and encrypting people's hashes to reach the
+ * machines' tokens is the wrong trade. The machine credential belongs somewhere of its own;
+ * that is the Principal / Credential split, §8 step 4 of `docs/design/auth-rebuild.md`.
+ */
+export declare const credentialAtRestTransformer: ValueTransformer;

package/dist-server/utils/credential-at-rest.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.credentialAtRestTransformer = void 0;
+const shell_1 = require("@things-factory/shell");
+const credential_features_js_1 = require("./credential-features.js");
+/**
+ * A credential column that encrypts only where the installation asked for it (ADR-0085).
+ *
+ * ── The switch governs writing. Reading always takes both ───────────────────
+ * `shell`'s `encryptTransformer` reads a value that is not ciphertext-shaped as plaintext, so
+ * rows written before the switch was turned on stay readable, and each row converts the next
+ * time something writes it. That behaviour does **not** move with the switch — if it did,
+ * turning the feature off would lose every row written while it was on.
+ *
+ * So off means "write it the way we always did", not "pretend the encrypted rows are not
+ * there".
+ *
+ * ── The switch is read per write, not once at import ────────────────────────
+ * A module-level constant would freeze whatever the config looked like when the entity file was
+ * first loaded, which is not the same thing in tests and not obviously the same thing at boot.
+ * `to` asks each time; it is a property lookup.
+ *
+ * ── Where this is NOT used: `User.password` ─────────────────────────────────
+ * That column holds a different thing depending on who the row is. For a person it is an HMAC
+ * of their password — already not the secret, so encrypting it protects nothing. For an
+ * appliance or an app binding it is the token itself, which is exactly what this is for.
+ *
+ * A column transformer cannot tell those apart, and encrypting people's hashes to reach the
+ * machines' tokens is the wrong trade. The machine credential belongs somewhere of its own;
+ * that is the Principal / Credential split, §8 step 4 of `docs/design/auth-rebuild.md`.
+ */
+exports.credentialAtRestTransformer = {
+    to: (entityValue) => ((0, credential_features_js_1.encryptsCredentialsAtRest)() ? shell_1.encryptTransformer.to(entityValue) : entityValue),
+    from: (databaseValue) => shell_1.encryptTransformer.from(databaseValue)
+};
+//# sourceMappingURL=credential-at-rest.js.map

package/dist-server/utils/credential-at-rest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-at-rest.js","sourceRoot":"","sources":["../../server/utils/credential-at-rest.ts"],"names":[],"mappings":";;;AAEA,iDAA0D;AAE1D,qEAAoE;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACU,QAAA,2BAA2B,GAAqB;IAC3D,EAAE,EAAE,CAAC,WAAmB,EAAE,EAAE,CAAC,CAAC,IAAA,kDAAyB,GAAE,CAAC,CAAC,CAAC,0BAAkB,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;IAE7G,IAAI,EAAE,CAAC,aAAqB,EAAE,EAAE,CAAC,0BAAkB,CAAC,IAAI,CAAC,aAAa,CAAC;CACxE,CAAA","sourcesContent":["import { ValueTransformer } from 'typeorm'\n\nimport { encryptTransformer } from '@things-factory/shell'\n\nimport { encryptsCredentialsAtRest } from './credential-features.js'\n\n/**\n * A credential column that encrypts only where the installation asked for it (ADR-0085).\n *\n * ── The switch governs writing. Reading always takes both ───────────────────\n * `shell`'s `encryptTransformer` reads a value that is not ciphertext-shaped as plaintext, so\n * rows written before the switch was turned on stay readable, and each row converts the next\n * time something writes it. That behaviour does **not** move with the switch — if it did,\n * turning the feature off would lose every row written while it was on.\n *\n * So off means \"write it the way we always did\", not \"pretend the encrypted rows are not\n * there\".\n *\n * ── The switch is read per write, not once at import ────────────────────────\n * A module-level constant would freeze whatever the config looked like when the entity file was\n * first loaded, which is not the same thing in tests and not obviously the same thing at boot.\n * `to` asks each time; it is a property lookup.\n *\n * ── Where this is NOT used: `User.password` ─────────────────────────────────\n * That column holds a different thing depending on who the row is. For a person it is an HMAC\n * of their password — already not the secret, so encrypting it protects nothing. For an\n * appliance or an app binding it is the token itself, which is exactly what this is for.\n *\n * A column transformer cannot tell those apart, and encrypting people's hashes to reach the\n * machines' tokens is the wrong trade. The machine credential belongs somewhere of its own;\n * that is the Principal / Credential split, §8 step 4 of `docs/design/auth-rebuild.md`.\n */\nexport const credentialAtRestTransformer: ValueTransformer = {\n  to: (entityValue: string) => (encryptsCredentialsAtRest() ? encryptTransformer.to(entityValue) : entityValue),\n\n  from: (databaseValue: string) => encryptTransformer.from(databaseValue)\n}\n"]}

package/dist-server/utils/credential-features.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The two credential features an installation turns on for itself (ADR-0085).
+ *
+ * ── Why they are switches and not just code ─────────────────────────────────
+ * An appliance token lives a year, and the ones already out in the field were issued by the
+ * version running now. Shipping either feature as plain behaviour would change what those
+ * deployments do the moment they take the release. So the installation decides, and a
+ * deployment that changes nothing keeps working exactly as it does today.
+ *
+ * `config.get(key, false)` answers the default when the key is absent, so "not configured"
+ * and "off" are the same thing here.
+ *
+ * ⚠ That `get` treats every falsy value as absent, so writing `false` in the config file also
+ * lands on the default. It matches while the default is `false`. **Do not flip these defaults
+ * to `true`** — turning them off again would stop working, and the only way off would be to
+ * delete the key.
+ */
+/**
+ * Store credentials as ciphertext rather than plaintext.
+ *
+ * ⚠ This governs **writing only**. Reading always accepts both shapes — see
+ * `shell/server/typeorm/encrypt-transform.ts`. If reading followed the switch, turning the
+ * feature off would lose every row written while it was on.
+ */
+export declare function encryptsCredentialsAtRest(): boolean;
+/**
+ * Offer revocation of an issued credential.
+ *
+ * ⚠ This governs **the door only** — whether the mutation and its screen exist. It does not
+ * govern whether an existing revocation holds. A credential revoked while this was on stays
+ * revoked after it is turned off, because a lost device must not come back through a config
+ * change. The check that enforces it does nothing on its own: a subject that was never
+ * revoked carries no serial, and the comparison never fires.
+ */
+export declare function offersCredentialRevocation(): boolean;

package/dist-server/utils/credential-features.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encryptsCredentialsAtRest = encryptsCredentialsAtRest;
+exports.offersCredentialRevocation = offersCredentialRevocation;
+const env_1 = require("@things-factory/env");
+/**
+ * The two credential features an installation turns on for itself (ADR-0085).
+ *
+ * ── Why they are switches and not just code ─────────────────────────────────
+ * An appliance token lives a year, and the ones already out in the field were issued by the
+ * version running now. Shipping either feature as plain behaviour would change what those
+ * deployments do the moment they take the release. So the installation decides, and a
+ * deployment that changes nothing keeps working exactly as it does today.
+ *
+ * `config.get(key, false)` answers the default when the key is absent, so "not configured"
+ * and "off" are the same thing here.
+ *
+ * ⚠ That `get` treats every falsy value as absent, so writing `false` in the config file also
+ * lands on the default. It matches while the default is `false`. **Do not flip these defaults
+ * to `true`** — turning them off again would stop working, and the only way off would be to
+ * delete the key.
+ */
+/**
+ * Store credentials as ciphertext rather than plaintext.
+ *
+ * ⚠ This governs **writing only**. Reading always accepts both shapes — see
+ * `shell/server/typeorm/encrypt-transform.ts`. If reading followed the switch, turning the
+ * feature off would lose every row written while it was on.
+ */
+function encryptsCredentialsAtRest() {
+    return !!env_1.config.get('credential/encryptAtRest', false);
+}
+/**
+ * Offer revocation of an issued credential.
+ *
+ * ⚠ This governs **the door only** — whether the mutation and its screen exist. It does not
+ * govern whether an existing revocation holds. A credential revoked while this was on stays
+ * revoked after it is turned off, because a lost device must not come back through a config
+ * change. The check that enforces it does nothing on its own: a subject that was never
+ * revoked carries no serial, and the comparison never fires.
+ */
+function offersCredentialRevocation() {
+    return !!env_1.config.get('credential/revocable', false);
+}
+//# sourceMappingURL=credential-features.js.map

package/dist-server/utils/credential-features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-features.js","sourceRoot":"","sources":["../../server/utils/credential-features.ts"],"names":[],"mappings":";;AA2BA,8DAEC;AAWD,gEAEC;AA1CD,6CAA4C;AAE5C;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;GAMG;AACH,SAAgB,yBAAyB;IACvC,OAAO,CAAC,CAAC,YAAM,CAAC,GAAG,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAA;AACxD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,0BAA0B;IACxC,OAAO,CAAC,CAAC,YAAM,CAAC,GAAG,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAA;AACpD,CAAC","sourcesContent":["import { config } from '@things-factory/env'\n\n/**\n * The two credential features an installation turns on for itself (ADR-0085).\n *\n * ── Why they are switches and not just code ─────────────────────────────────\n * An appliance token lives a year, and the ones already out in the field were issued by the\n * version running now. Shipping either feature as plain behaviour would change what those\n * deployments do the moment they take the release. So the installation decides, and a\n * deployment that changes nothing keeps working exactly as it does today.\n *\n * `config.get(key, false)` answers the default when the key is absent, so \"not configured\"\n * and \"off\" are the same thing here.\n *\n * ⚠ That `get` treats every falsy value as absent, so writing `false` in the config file also\n * lands on the default. It matches while the default is `false`. **Do not flip these defaults\n * to `true`** — turning them off again would stop working, and the only way off would be to\n * delete the key.\n */\n\n/**\n * Store credentials as ciphertext rather than plaintext.\n *\n * ⚠ This governs **writing only**. Reading always accepts both shapes — see\n * `shell/server/typeorm/encrypt-transform.ts`. If reading followed the switch, turning the\n * feature off would lose every row written while it was on.\n */\nexport function encryptsCredentialsAtRest(): boolean {\n  return !!config.get('credential/encryptAtRest', false)\n}\n\n/**\n * Offer revocation of an issued credential.\n *\n * ⚠ This governs **the door only** — whether the mutation and its screen exist. It does not\n * govern whether an existing revocation holds. A credential revoked while this was on stays\n * revoked after it is turned off, because a lost device must not come back through a config\n * change. The check that enforces it does nothing on its own: a subject that was never\n * revoked carries no serial, and the comparison never fires.\n */\nexport function offersCredentialRevocation(): boolean {\n  return !!config.get('credential/revocable', false)\n}\n"]}

package/dist-server/utils/credential-serial-rule.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Does this token still name the current generation of its subject's credential? (Pure rule.)
+ *
+ * ## Why the rule is its own function
+ *
+ * `checkAuth` runs on every request, and this is the one line in it that can refuse a token
+ * whose signature is perfectly good. A rule that decides that belongs somewhere it can be read
+ * and tested on its own, next to `account-lock-rule` and `checkin-domain-rule`.
+ *
+ * ## What an absent serial means, and why it must pass
+ *
+ * An appliance token lives a year. The ones in the field were signed before the column existed,
+ * so they carry no serial, and the subjects they name have none recorded. **Those have to pass**
+ * — otherwise taking the release cuts off every device at once, and the point of the design was
+ * that it does not (ADR-0085 decision 3).
+ *
+ * A subject gains a serial the first time its credential is issued or revoked. From that moment
+ * its tokens have to carry the same number, and an older one no longer does.
+ *
+ * ## Why this closes what a status could not
+ *
+ * Revocation used to live entirely in the shadow user's status, which meant putting the status
+ * back let every token ever issued to that appliance work again. The serial moves on revoke and
+ * never moves back, so reactivating a subject does not resurrect its old credentials — only
+ * issuing a new one does, and that one carries the new number.
+ */
+/** The parts of the subject this rule reads. */
+export type CredentialSubject = {
+    credentialSerial?: number | null;
+};
+/** The parts of a verified token this rule reads. `cs` is absent on anything issued earlier. */
+export type CredentialClaims = {
+    cs?: number | null;
+};
+/**
+ * True when the token may still be used for this subject.
+ *
+ * Absent-on-the-subject means this subject has never been through the new path, and everything
+ * passes. Present means the token has to match it exactly.
+ */
+export declare function credentialSerialMatches(subject: CredentialSubject, claims: CredentialClaims): boolean;

package/dist-server/utils/credential-serial-rule.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Does this token still name the current generation of its subject's credential? (Pure rule.)
+ *
+ * ## Why the rule is its own function
+ *
+ * `checkAuth` runs on every request, and this is the one line in it that can refuse a token
+ * whose signature is perfectly good. A rule that decides that belongs somewhere it can be read
+ * and tested on its own, next to `account-lock-rule` and `checkin-domain-rule`.
+ *
+ * ## What an absent serial means, and why it must pass
+ *
+ * An appliance token lives a year. The ones in the field were signed before the column existed,
+ * so they carry no serial, and the subjects they name have none recorded. **Those have to pass**
+ * — otherwise taking the release cuts off every device at once, and the point of the design was
+ * that it does not (ADR-0085 decision 3).
+ *
+ * A subject gains a serial the first time its credential is issued or revoked. From that moment
+ * its tokens have to carry the same number, and an older one no longer does.
+ *
+ * ## Why this closes what a status could not
+ *
+ * Revocation used to live entirely in the shadow user's status, which meant putting the status
+ * back let every token ever issued to that appliance work again. The serial moves on revoke and
+ * never moves back, so reactivating a subject does not resurrect its old credentials — only
+ * issuing a new one does, and that one carries the new number.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.credentialSerialMatches = credentialSerialMatches;
+/**
+ * True when the token may still be used for this subject.
+ *
+ * Absent-on-the-subject means this subject has never been through the new path, and everything
+ * passes. Present means the token has to match it exactly.
+ */
+function credentialSerialMatches(subject, claims) {
+    const current = subject?.credentialSerial;
+    if (current === null || current === undefined) {
+        return true;
+    }
+    return claims?.cs === current;
+}
+//# sourceMappingURL=credential-serial-rule.js.map

package/dist-server/utils/credential-serial-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-serial-rule.js","sourceRoot":"","sources":["../../server/utils/credential-serial-rule.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;AAkBH,0DAQC;AAdD;;;;;GAKG;AACH,SAAgB,uBAAuB,CAAC,OAA0B,EAAE,MAAwB;IAC1F,MAAM,OAAO,GAAG,OAAO,EAAE,gBAAgB,CAAA;IAEzC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,MAAM,EAAE,EAAE,KAAK,OAAO,CAAA;AAC/B,CAAC","sourcesContent":["/**\n * Does this token still name the current generation of its subject's credential? (Pure rule.)\n *\n * ## Why the rule is its own function\n *\n * `checkAuth` runs on every request, and this is the one line in it that can refuse a token\n * whose signature is perfectly good. A rule that decides that belongs somewhere it can be read\n * and tested on its own, next to `account-lock-rule` and `checkin-domain-rule`.\n *\n * ## What an absent serial means, and why it must pass\n *\n * An appliance token lives a year. The ones in the field were signed before the column existed,\n * so they carry no serial, and the subjects they name have none recorded. **Those have to pass**\n * — otherwise taking the release cuts off every device at once, and the point of the design was\n * that it does not (ADR-0085 decision 3).\n *\n * A subject gains a serial the first time its credential is issued or revoked. From that moment\n * its tokens have to carry the same number, and an older one no longer does.\n *\n * ## Why this closes what a status could not\n *\n * Revocation used to live entirely in the shadow user's status, which meant putting the status\n * back let every token ever issued to that appliance work again. The serial moves on revoke and\n * never moves back, so reactivating a subject does not resurrect its old credentials — only\n * issuing a new one does, and that one carries the new number.\n */\n\n/** The parts of the subject this rule reads. */\nexport type CredentialSubject = {\n  credentialSerial?: number | null\n}\n\n/** The parts of a verified token this rule reads. `cs` is absent on anything issued earlier. */\nexport type CredentialClaims = {\n  cs?: number | null\n}\n\n/**\n * True when the token may still be used for this subject.\n *\n * Absent-on-the-subject means this subject has never been through the new path, and everything\n * passes. Present means the token has to match it exactly.\n */\nexport function credentialSerialMatches(subject: CredentialSubject, claims: CredentialClaims): boolean {\n  const current = subject?.credentialSerial\n\n  if (current === null || current === undefined) {\n    return true\n  }\n\n  return claims?.cs === current\n}\n"]}

package/dist-server/utils/invitation-state.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What state an invitation is in, and whether it can still be accepted. (Pure rule.)
+ *
+ * ## Why the table keeps rows now
+ *
+ * Accepting used to delete the row and cancelling still does, so the table was a queue of
+ * pending invitations and nothing else. The moment somebody joined, the fact that they had been
+ * invited stopped existing — which is why no screen was ever built on it, and why nothing calls
+ * any of it. An invitation list has to be able to say *who was invited, by whom, when, and
+ * whether they came in*.
+ *
+ * So the row survives and carries its state. `pending` → one of the other three, and never back.
+ *
+ * ## Why expiry is derived and not only stored
+ *
+ * A token that outlives its invitation is a credential nobody is watching. If `expired` were
+ * only ever a written value, it would depend on something running to write it, and the gap
+ * between the expiry passing and that thing running is a window where the token still works.
+ * So the rule reads the clock: a pending row past its `expiresAt` **is** expired, whatever the
+ * column says. Writing the status is then bookkeeping for the list, not the guard.
+ *
+ * ## What an absent value means, and why it refuses
+ *
+ * Rows written before this existed have neither status nor expiry. They come from a flow that
+ * never completed — the link in the email led nowhere — so treating them as live would keep
+ * tokens alive that were never usable in the first place.
+ *
+ *   status absent       reads as `pending`, which is what the old table meant by a row existing
+ *   expiresAt absent    reads as **expired**. An invitation that cannot say when it dies is not
+ *                       a live invitation, and this is a credential: absence refuses.
+ */
+/** The states an invitation row can be in. Stored, and also derived for expiry. */
+export declare enum InvitationStatus {
+    PENDING = "pending",
+    ACCEPTED = "accepted",
+    CANCELLED = "cancelled",
+    EXPIRED = "expired"
+}
+/** The parts of an invitation this rule reads. */
+export type InvitationRecord = {
+    status?: string | null;
+    expiresAt?: Date | string | null;
+} | null | undefined;
+/**
+ * The state this invitation is in, as of `now`.
+ *
+ * Only a pending row is measured against the clock. Once a row has been accepted or cancelled
+ * that is what happened to it, and time passing does not rewrite history.
+ */
+export declare function invitationState(invitation: InvitationRecord, now?: Date): InvitationStatus;
+/** May this invitation still be accepted? Only a pending one that has not run out. */
+export declare function mayAccept(invitation: InvitationRecord, now?: Date): boolean;

package/dist-server/utils/invitation-state.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * What state an invitation is in, and whether it can still be accepted. (Pure rule.)
+ *
+ * ## Why the table keeps rows now
+ *
+ * Accepting used to delete the row and cancelling still does, so the table was a queue of
+ * pending invitations and nothing else. The moment somebody joined, the fact that they had been
+ * invited stopped existing — which is why no screen was ever built on it, and why nothing calls
+ * any of it. An invitation list has to be able to say *who was invited, by whom, when, and
+ * whether they came in*.
+ *
+ * So the row survives and carries its state. `pending` → one of the other three, and never back.
+ *
+ * ## Why expiry is derived and not only stored
+ *
+ * A token that outlives its invitation is a credential nobody is watching. If `expired` were
+ * only ever a written value, it would depend on something running to write it, and the gap
+ * between the expiry passing and that thing running is a window where the token still works.
+ * So the rule reads the clock: a pending row past its `expiresAt` **is** expired, whatever the
+ * column says. Writing the status is then bookkeeping for the list, not the guard.
+ *
+ * ## What an absent value means, and why it refuses
+ *
+ * Rows written before this existed have neither status nor expiry. They come from a flow that
+ * never completed — the link in the email led nowhere — so treating them as live would keep
+ * tokens alive that were never usable in the first place.
+ *
+ *   status absent       reads as `pending`, which is what the old table meant by a row existing
+ *   expiresAt absent    reads as **expired**. An invitation that cannot say when it dies is not
+ *                       a live invitation, and this is a credential: absence refuses.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvitationStatus = void 0;
+exports.invitationState = invitationState;
+exports.mayAccept = mayAccept;
+/** The states an invitation row can be in. Stored, and also derived for expiry. */
+var InvitationStatus;
+(function (InvitationStatus) {
+    InvitationStatus["PENDING"] = "pending";
+    InvitationStatus["ACCEPTED"] = "accepted";
+    InvitationStatus["CANCELLED"] = "cancelled";
+    InvitationStatus["EXPIRED"] = "expired";
+})(InvitationStatus || (exports.InvitationStatus = InvitationStatus = {}));
+function expiryPassed(expiresAt, now) {
+    if (!expiresAt) {
+        /* No expiry recorded — see the note above. Absence refuses. */
+        return true;
+    }
+    const at = expiresAt instanceof Date ? expiresAt : new Date(expiresAt);
+    if (Number.isNaN(at.getTime())) {
+        return true;
+    }
+    return at.getTime() <= now.getTime();
+}
+/**
+ * The state this invitation is in, as of `now`.
+ *
+ * Only a pending row is measured against the clock. Once a row has been accepted or cancelled
+ * that is what happened to it, and time passing does not rewrite history.
+ */
+function invitationState(invitation, now = new Date()) {
+    const status = invitation?.status || InvitationStatus.PENDING;
+    if (status === InvitationStatus.ACCEPTED || status === InvitationStatus.CANCELLED) {
+        return status;
+    }
+    if (status === InvitationStatus.EXPIRED) {
+        return InvitationStatus.EXPIRED;
+    }
+    return expiryPassed(invitation?.expiresAt, now) ? InvitationStatus.EXPIRED : InvitationStatus.PENDING;
+}
+/** May this invitation still be accepted? Only a pending one that has not run out. */
+function mayAccept(invitation, now = new Date()) {
+    return !!invitation && invitationState(invitation, now) === InvitationStatus.PENDING;
+}
+//# sourceMappingURL=invitation-state.js.map

package/dist-server/utils/invitation-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invitation-state.js","sourceRoot":"","sources":["../../server/utils/invitation-state.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;AAqCH,0CAYC;AAGD,8BAEC;AApDD,mFAAmF;AACnF,IAAY,gBAKX;AALD,WAAY,gBAAgB;IAC1B,uCAAmB,CAAA;IACnB,yCAAqB,CAAA;IACrB,2CAAuB,CAAA;IACvB,uCAAmB,CAAA;AACrB,CAAC,EALW,gBAAgB,gCAAhB,gBAAgB,QAK3B;AAQD,SAAS,YAAY,CAAC,SAA2C,EAAE,GAAS;IAC1E,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,+DAA+D;QAC/D,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,EAAE,GAAG,SAAS,YAAY,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAA;IAEtE,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,EAAE,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE,CAAA;AACtC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,UAA4B,EAAE,MAAY,IAAI,IAAI,EAAE;IAClF,MAAM,MAAM,GAAG,UAAU,EAAE,MAAM,IAAI,gBAAgB,CAAC,OAAO,CAAA;IAE7D,IAAI,MAAM,KAAK,gBAAgB,CAAC,QAAQ,IAAI,MAAM,KAAK,gBAAgB,CAAC,SAAS,EAAE,CAAC;QAClF,OAAO,MAA0B,CAAA;IACnC,CAAC;IAED,IAAI,MAAM,KAAK,gBAAgB,CAAC,OAAO,EAAE,CAAC;QACxC,OAAO,gBAAgB,CAAC,OAAO,CAAA;IACjC,CAAC;IAED,OAAO,YAAY,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAA;AACvG,CAAC;AAED,sFAAsF;AACtF,SAAgB,SAAS,CAAC,UAA4B,EAAE,MAAY,IAAI,IAAI,EAAE;IAC5E,OAAO,CAAC,CAAC,UAAU,IAAI,eAAe,CAAC,UAAU,EAAE,GAAG,CAAC,KAAK,gBAAgB,CAAC,OAAO,CAAA;AACtF,CAAC","sourcesContent":["/**\n * What state an invitation is in, and whether it can still be accepted. (Pure rule.)\n *\n * ## Why the table keeps rows now\n *\n * Accepting used to delete the row and cancelling still does, so the table was a queue of\n * pending invitations and nothing else. The moment somebody joined, the fact that they had been\n * invited stopped existing — which is why no screen was ever built on it, and why nothing calls\n * any of it. An invitation list has to be able to say *who was invited, by whom, when, and\n * whether they came in*.\n *\n * So the row survives and carries its state. `pending` → one of the other three, and never back.\n *\n * ## Why expiry is derived and not only stored\n *\n * A token that outlives its invitation is a credential nobody is watching. If `expired` were\n * only ever a written value, it would depend on something running to write it, and the gap\n * between the expiry passing and that thing running is a window where the token still works.\n * So the rule reads the clock: a pending row past its `expiresAt` **is** expired, whatever the\n * column says. Writing the status is then bookkeeping for the list, not the guard.\n *\n * ## What an absent value means, and why it refuses\n *\n * Rows written before this existed have neither status nor expiry. They come from a flow that\n * never completed — the link in the email led nowhere — so treating them as live would keep\n * tokens alive that were never usable in the first place.\n *\n *   status absent       reads as `pending`, which is what the old table meant by a row existing\n *   expiresAt absent    reads as **expired**. An invitation that cannot say when it dies is not\n *                       a live invitation, and this is a credential: absence refuses.\n */\n\n/** The states an invitation row can be in. Stored, and also derived for expiry. */\nexport enum InvitationStatus {\n  PENDING = 'pending',\n  ACCEPTED = 'accepted',\n  CANCELLED = 'cancelled',\n  EXPIRED = 'expired'\n}\n\n/** The parts of an invitation this rule reads. */\nexport type InvitationRecord = {\n  status?: string | null\n  expiresAt?: Date | string | null\n} | null | undefined\n\nfunction expiryPassed(expiresAt: Date | string | null | undefined, now: Date): boolean {\n  if (!expiresAt) {\n    /* No expiry recorded — see the note above. Absence refuses. */\n    return true\n  }\n\n  const at = expiresAt instanceof Date ? expiresAt : new Date(expiresAt)\n\n  if (Number.isNaN(at.getTime())) {\n    return true\n  }\n\n  return at.getTime() <= now.getTime()\n}\n\n/**\n * The state this invitation is in, as of `now`.\n *\n * Only a pending row is measured against the clock. Once a row has been accepted or cancelled\n * that is what happened to it, and time passing does not rewrite history.\n */\nexport function invitationState(invitation: InvitationRecord, now: Date = new Date()): InvitationStatus {\n  const status = invitation?.status || InvitationStatus.PENDING\n\n  if (status === InvitationStatus.ACCEPTED || status === InvitationStatus.CANCELLED) {\n    return status as InvitationStatus\n  }\n\n  if (status === InvitationStatus.EXPIRED) {\n    return InvitationStatus.EXPIRED\n  }\n\n  return expiryPassed(invitation?.expiresAt, now) ? InvitationStatus.EXPIRED : InvitationStatus.PENDING\n}\n\n/** May this invitation still be accepted? Only a pending one that has not run out. */\nexport function mayAccept(invitation: InvitationRecord, now: Date = new Date()): boolean {\n  return !!invitation && invitationState(invitation, now) === InvitationStatus.PENDING\n}\n"]}

package/dist-server/utils/refuse-role-name.d.ts

@@ -0,0 +1,42 @@
+import { EntityManager, Repository, SelectQueryBuilder } from 'typeorm';
+import { Role } from '../service/role/role.js';
+import { type AskingDomain } from './role-name-standing.js';
+/**
+ * The one place a role name is checked before it is written (ADR-0062 decision 3).
+ *
+ * ── Why it is one place ─────────────────────────────────────────────────────
+ * Five sites write a role name — `createRole`, the rename in `updateRole`, both halves of
+ * `updateMultipleRoles`, and `createRoleFromTemplate`. All five asked `domain: { id: domain.id }`
+ * and none of them looked at what the domain inherits. Five copies of a check is five chances
+ * for one of them to keep the old question.
+ *
+ * ── Why the refusal names the domain ────────────────────────────────────────
+ * The operator's next step differs by where the name stands. If it stands here they rename; if
+ * it is inherited they may decide this domain stands its own. They cannot choose without being
+ * told which it is and from where — a refusal that only says "duplicated" leaves them guessing
+ * at a domain they may not have known existed.
+ *
+ * ── Why a `Refusal` and not a sentence ──────────────────────────────────────
+ * The rest of this file's neighbours throw English strings, which puts English on a Korean
+ * screen and makes the screen write the reason itself (ADR-0054). This refusal is new, so it
+ * starts as a name and values; the older sentences around it are left alone.
+ */
+export declare function refuseRoleNameIfStanding({ name, domain, separately, tx }: {
+    name: string;
+    domain: AskingDomain;
+    separately?: boolean;
+    tx?: EntityManager;
+}): Promise<void>;
+/**
+ * The read behind the check: a role of this name **in one named domain**.
+ *
+ * ── Why this is a builder and not a `findOne` ───────────────────────────────
+ * One domain at a time is the whole point, and the harness that would catch it going back to
+ * both is sqlite — which returns the rows in an order that happens to be the right answer, so it
+ * cannot fail the way a server does. The repository's own note says as much about column
+ * dialects, and `domain-inheritance-sentinel.test.ts` says it about this exact class.
+ *
+ * So the query is something a test can read **before it is sent**. What we build is the same on
+ * every driver, which is the only way to reach a defect our sqlite development cannot see.
+ */
+export declare function standingRoleQuery(repository: Repository<Role>, name: string, domainId: string): SelectQueryBuilder<Role>;

package/dist-server/utils/refuse-role-name.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refuseRoleNameIfStanding = refuseRoleNameIfStanding;
+exports.standingRoleQuery = standingRoleQuery;
+const shell_1 = require("@things-factory/shell");
+const role_js_1 = require("../service/role/role.js");
+const role_name_standing_js_1 = require("./role-name-standing.js");
+/**
+ * The one place a role name is checked before it is written (ADR-0062 decision 3).
+ *
+ * ── Why it is one place ─────────────────────────────────────────────────────
+ * Five sites write a role name — `createRole`, the rename in `updateRole`, both halves of
+ * `updateMultipleRoles`, and `createRoleFromTemplate`. All five asked `domain: { id: domain.id }`
+ * and none of them looked at what the domain inherits. Five copies of a check is five chances
+ * for one of them to keep the old question.
+ *
+ * ── Why the refusal names the domain ────────────────────────────────────────
+ * The operator's next step differs by where the name stands. If it stands here they rename; if
+ * it is inherited they may decide this domain stands its own. They cannot choose without being
+ * told which it is and from where — a refusal that only says "duplicated" leaves them guessing
+ * at a domain they may not have known existed.
+ *
+ * ── Why a `Refusal` and not a sentence ──────────────────────────────────────
+ * The rest of this file's neighbours throw English strings, which puts English on a Korean
+ * screen and makes the screen write the reason itself (ADR-0054). This refusal is new, so it
+ * starts as a name and values; the older sentences around it are left alone.
+ */
+async function refuseRoleNameIfStanding({ name, domain, separately, tx }) {
+    const repository = (0, shell_1.getRepository)(role_js_1.Role, tx);
+    /*
+     * ⚠ This domain is asked first, on its own, and the parent only if it has nothing.
+     *
+     * One read over both with `In([own, parent])` has no `ORDER BY`, so when the name stands in
+     * **both** the answer is whichever row the driver hands back. If that is the parent's, the
+     * refusal is the inherited one — and `separately` is allowed to pass that, which stands a
+     * second row of the name in a domain that already has it. Exactly the state the rule exists to
+     * prevent, reached through the rule.
+     *
+     * Standing in both is not a corner: the migration of ADR-0062 decision 2 passes through it for
+     * its whole length, because the domain's own role stands up first and the parent is cut last.
+     *
+     * This is the same defect that `role(name)` had and the same fix. It went back in here because
+     * "one read" looked like the tidier shape.
+     */
+    const own = await standingRoleQuery(repository, name, domain.id).getOne();
+    const found = own || (domain.parentId ? await standingRoleQuery(repository, name, domain.parentId).getOne() : null);
+    const standing = (0, role_name_standing_js_1.nameStands)({ domainId: found?.domain?.id || found?.domainId }, domain);
+    if (!(0, role_name_standing_js_1.refusesName)(standing, separately)) {
+        return;
+    }
+    if (standing === 'here') {
+        throw new shell_1.Refusal('role-name-taken-here', { name }, `This domain already has a role called "${name}".`);
+    }
+    throw new shell_1.Refusal('role-name-stands-inherited', { name, domain: found?.domain?.name || '' }, `A role called "${name}" is already visible here, defined in "${found?.domain?.name}". ` +
+        `Stand this domain's own of that name only if that is what you mean to do.`);
+}
+/**
+ * The read behind the check: a role of this name **in one named domain**.
+ *
+ * ── Why this is a builder and not a `findOne` ───────────────────────────────
+ * One domain at a time is the whole point, and the harness that would catch it going back to
+ * both is sqlite — which returns the rows in an order that happens to be the right answer, so it
+ * cannot fail the way a server does. The repository's own note says as much about column
+ * dialects, and `domain-inheritance-sentinel.test.ts` says it about this exact class.
+ *
+ * So the query is something a test can read **before it is sent**. What we build is the same on
+ * every driver, which is the only way to reach a defect our sqlite development cannot see.
+ */
+function standingRoleQuery(repository, name, domainId) {
+    return repository
+        .createQueryBuilder('ROLE')
+        .leftJoinAndSelect('ROLE.domain', 'ROLE_DOMAIN')
+        .where('ROLE.name = :name', { name })
+        .andWhere('ROLE_DOMAIN.id = :domainId', { domainId });
+}
+//# sourceMappingURL=refuse-role-name.js.map

package/dist-server/utils/refuse-role-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refuse-role-name.js","sourceRoot":"","sources":["../../server/utils/refuse-role-name.ts"],"names":[],"mappings":";;AA2BA,4DAoDC;AAcD,8CAUC;AArGD,iDAA8D;AAE9D,qDAA8C;AAC9C,mEAAoF;AAEpF;;;;;;;;;;;;;;;;;;;GAmBG;AACI,KAAK,UAAU,wBAAwB,CAAC,EAC7C,IAAI,EACJ,MAAM,EACN,UAAU,EACV,EAAE,EAMH;IACC,MAAM,UAAU,GAAG,IAAA,qBAAa,EAAC,cAAI,EAAE,EAAE,CAAC,CAAA;IAE1C;;;;;;;;;;;;;;OAcG;IACH,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;IAEzE,MAAM,KAAK,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,iBAAiB,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IAEnH,MAAM,QAAQ,GAAG,IAAA,kCAAU,EAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,CAAC,CAAA;IAEvF,IAAI,CAAC,IAAA,mCAAW,EAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,CAAC;QACvC,OAAM;IACR,CAAC;IAED,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,MAAM,IAAI,eAAO,CACf,sBAAsB,EACtB,EAAE,IAAI,EAAE,EACR,0CAA0C,IAAI,IAAI,CACnD,CAAA;IACH,CAAC;IAED,MAAM,IAAI,eAAO,CACf,4BAA4B,EAC5B,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,IAAI,EAAE,EAAE,EAC3C,kBAAkB,IAAI,0CAA0C,KAAK,EAAE,MAAM,EAAE,IAAI,KAAK;QACtF,2EAA2E,CAC9E,CAAA;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,iBAAiB,CAC/B,UAA4B,EAC5B,IAAY,EACZ,QAAgB;IAEhB,OAAO,UAAU;SACd,kBAAkB,CAAC,MAAM,CAAC;SAC1B,iBAAiB,CAAC,aAAa,EAAE,aAAa,CAAC;SAC/C,KAAK,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,CAAC;SACpC,QAAQ,CAAC,4BAA4B,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAA;AACzD,CAAC","sourcesContent":["import { EntityManager, Repository, SelectQueryBuilder } from 'typeorm'\n\nimport { getRepository, Refusal } from '@things-factory/shell'\n\nimport { Role } from '../service/role/role.js'\nimport { nameStands, refusesName, type AskingDomain } from './role-name-standing.js'\n\n/**\n * The one place a role name is checked before it is written (ADR-0062 decision 3).\n *\n * ── Why it is one place ─────────────────────────────────────────────────────\n * Five sites write a role name — `createRole`, the rename in `updateRole`, both halves of\n * `updateMultipleRoles`, and `createRoleFromTemplate`. All five asked `domain: { id: domain.id }`\n * and none of them looked at what the domain inherits. Five copies of a check is five chances\n * for one of them to keep the old question.\n *\n * ── Why the refusal names the domain ────────────────────────────────────────\n * The operator's next step differs by where the name stands. If it stands here they rename; if\n * it is inherited they may decide this domain stands its own. They cannot choose without being\n * told which it is and from where — a refusal that only says \"duplicated\" leaves them guessing\n * at a domain they may not have known existed.\n *\n * ── Why a `Refusal` and not a sentence ──────────────────────────────────────\n * The rest of this file's neighbours throw English strings, which puts English on a Korean\n * screen and makes the screen write the reason itself (ADR-0054). This refusal is new, so it\n * starts as a name and values; the older sentences around it are left alone.\n */\nexport async function refuseRoleNameIfStanding({\n  name,\n  domain,\n  separately,\n  tx\n}: {\n  name: string\n  domain: AskingDomain\n  separately?: boolean\n  tx?: EntityManager\n}): Promise<void> {\n  const repository = getRepository(Role, tx)\n\n  /*\n   * ⚠ This domain is asked first, on its own, and the parent only if it has nothing.\n   *\n   * One read over both with `In([own, parent])` has no `ORDER BY`, so when the name stands in\n   * **both** the answer is whichever row the driver hands back. If that is the parent's, the\n   * refusal is the inherited one — and `separately` is allowed to pass that, which stands a\n   * second row of the name in a domain that already has it. Exactly the state the rule exists to\n   * prevent, reached through the rule.\n   *\n   * Standing in both is not a corner: the migration of ADR-0062 decision 2 passes through it for\n   * its whole length, because the domain's own role stands up first and the parent is cut last.\n   *\n   * This is the same defect that `role(name)` had and the same fix. It went back in here because\n   * \"one read\" looked like the tidier shape.\n   */\n  const own = await standingRoleQuery(repository, name, domain.id).getOne()\n\n  const found = own || (domain.parentId ? await standingRoleQuery(repository, name, domain.parentId).getOne() : null)\n\n  const standing = nameStands({ domainId: found?.domain?.id || found?.domainId }, domain)\n\n  if (!refusesName(standing, separately)) {\n    return\n  }\n\n  if (standing === 'here') {\n    throw new Refusal(\n      'role-name-taken-here',\n      { name },\n      `This domain already has a role called \"${name}\".`\n    )\n  }\n\n  throw new Refusal(\n    'role-name-stands-inherited',\n    { name, domain: found?.domain?.name || '' },\n    `A role called \"${name}\" is already visible here, defined in \"${found?.domain?.name}\". ` +\n      `Stand this domain's own of that name only if that is what you mean to do.`\n  )\n}\n\n/**\n * The read behind the check: a role of this name **in one named domain**.\n *\n * ── Why this is a builder and not a `findOne` ───────────────────────────────\n * One domain at a time is the whole point, and the harness that would catch it going back to\n * both is sqlite — which returns the rows in an order that happens to be the right answer, so it\n * cannot fail the way a server does. The repository's own note says as much about column\n * dialects, and `domain-inheritance-sentinel.test.ts` says it about this exact class.\n *\n * So the query is something a test can read **before it is sent**. What we build is the same on\n * every driver, which is the only way to reach a defect our sqlite development cannot see.\n */\nexport function standingRoleQuery(\n  repository: Repository<Role>,\n  name: string,\n  domainId: string\n): SelectQueryBuilder<Role> {\n  return repository\n    .createQueryBuilder('ROLE')\n    .leftJoinAndSelect('ROLE.domain', 'ROLE_DOMAIN')\n    .where('ROLE.name = :name', { name })\n    .andWhere('ROLE_DOMAIN.id = :domainId', { domainId })\n}\n"]}

package/dist-server/utils/role-name-standing.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Whether a role may be given a name that is already standing. (Pure rule — ADR-0062 decision 3.)
+ *
+ * ## The situation
+ *
+ * A domain sees its own roles and its parent's. Until this rule, the duplicate checks asked only
+ * about the domain itself, so a domain with a parent could be given a role whose name was already
+ * visible through inheritance. Two rows then answered to one name: every list showed both, and
+ * resolving the name picked one. An approval line could end up pointing at the one nobody looks
+ * at.
+ *
+ * ## What is refused, and what is not
+ *
+ * ```
+ * here        the domain already has this name          always refused
+ * inherited   the parent has it and this domain not     refused unless the operator says so
+ * nowhere     neither                                   stands
+ * ```
+ *
+ * ## Why the escape hatch does not ask for a different name
+ *
+ * ⚠ This is the part that is easy to get backwards. ADR-0062 decision 2 sets out the only path
+ * for moving a domain off an inherited structure: **stand the role up here → move the people to
+ * the role of the same name → cut the parent last.** The name being the same is the point of it
+ * — the domain's own role is standing up to *replace* what it inherits, and once the parent is
+ * cut there is one name again.
+ *
+ * So requiring a different name would close the one route decision 2 defines. The escape is the
+ * operator saying, in as many words, that this domain stands its own — and the name stays.
+ * Asking for a different name remains available on top of that, for when somebody genuinely
+ * wants a second seat with the same privileges; it is a choice, never a requirement.
+ */
+/** Where a role of this name already stands, seen from the domain that is asking. */
+export type NameStanding = 'nowhere' | 'here' | 'inherited';
+/** The domain asking. `parentId` absent means it inherits from nobody. */
+export type AskingDomain = {
+    id: string;
+    parentId?: string | null;
+};
+/** A role that was found carrying the name, or nothing. */
+export type StandingRole = {
+    domainId?: string | null;
+} | null | undefined;
+/**
+ * Where the name stands.
+ *
+ * A role found in neither this domain nor its parent is `nowhere` — the caller is expected to
+ * have looked in those two places, and a row from somewhere else is not this domain's business.
+ */
+export declare function nameStands(found: StandingRole, domain: AskingDomain): NameStanding;
+/**
+ * Does the name refuse?
+ *
+ * `separately` is the operator saying this domain stands its own of that name. It reaches only
+ * the inherited case — a name already taken **in this domain** is not a thing anybody can opt
+ * into, because the two rows would be indistinguishable in every respect.
+ */
+export declare function refusesName(standing: NameStanding, separately?: boolean): boolean;