@noctcore/lint-meta-rules 0.5.0 → 0.6.1

package/dist/session.d.cts

@@ -0,0 +1,226 @@
+import { IMetaRule } from '@noctcore/harness';
+
+/**
+ * The source scope every session rule shares: which files are read, and which
+ * of them are left alone because they drive the seam directly (tests).
+ */
+interface SessionSourceScopeOptions {
+    /**
+     * Globs of the application source that can open a session, relative to the
+     * repo root. Empty (the default) makes the rule inert: it reads nothing and
+     * reports nothing. Point it at shipped code only; a lint-meta rule module that
+     * quotes the call in its own pattern is not a call site.
+     */
+    readonly sourceGlobs?: readonly string[];
+    /** Paths with any of these segments are skipped. Default `node_modules`, `.git`, `dist`, `.turbo`, `coverage`. */
+    readonly skipDirs?: readonly string[];
+    /**
+     * Files ending in any of these are skipped: tests drive the seam directly,
+     * including shapes production never produces. Default
+     * `['.spec.ts', '.spec.tsx', '.test.ts', '.test.tsx']`.
+     */
+    readonly excludeSuffixes?: readonly string[];
+}
+/**
+ * The argument text of each `.<method>(...)` call in `source`.
+ *
+ * Scanned by balancing parentheses rather than matched with a regex: an options
+ * object spans lines and holds its own braces and parens, and a non-greedy
+ * regex either stops early or runs on into the next call. A scanner that never
+ * finds the closing paren returns what it has, which is the fail-closed
+ * direction (more text to search, never less). `.<method>Something(` is not a
+ * call of `method`: only whitespace may sit between the name and the paren.
+ */
+declare function callArguments(source: string, method: string): string[];
+
+/**
+ * Options for {@link createSessionEpochCapturedRule}.
+ *
+ * Ported from Settly, which hardcoded the seam (`beginOrEstablish`), the field
+ * (`epoch`) and the seam's own file. With no `call` the rule is inert.
+ */
+interface SessionEpochCapturedOptions extends SessionSourceScopeOptions {
+    /** Rule id, for running more than one instance. Default `session-epoch-captured`. */
+    readonly id?: string;
+    /**
+     * The post-credential seam every sign-in passes through on its way to a
+     * session, matched as `.<call>(`. Unset or empty = inert.
+     */
+    readonly call?: string;
+    /** The argument every call must mention: the epoch captured before the credential was read. Default `epoch`. */
+    readonly field?: string;
+    /**
+     * Repo-relative files skipped outright: the seam's own home, which defines
+     * the method and may call itself without a captured value. Default: none.
+     */
+    readonly exempt?: readonly string[];
+    /** How the epoch is captured (e.g. `sessions.readEpoch(userId)`), quoted in the message. Optional. */
+    readonly captureCall?: string;
+    /** Appended to every message: a pointer to the project's own docs. */
+    readonly hint?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Every call into the sign-in seam passes the session epoch it captured before
+ * reading the credential.
+ *
+ * A revoke-all bumps a per-user epoch and a mint refuses to write a session
+ * under a stale one. Captured inside the mint, the fence covers the store write
+ * and nothing else: the whole credential check (a password hash verify, an
+ * OAuth token exchange) is a window in which a sign-in that already read the
+ * revoked state still mints a surviving session. So each entry point captures
+ * the epoch first and hands it to the seam, and this rule fails any call whose
+ * arguments never mention it.
+ */
+declare function createSessionEpochCapturedRule(options?: SessionEpochCapturedOptions): IMetaRule;
+
+/**
+ * Options for {@link createSessionKindStampedRule}.
+ *
+ * Ported from Settly, which hardcoded the mint (`establishSession`), the field
+ * (`kind`) and the one staff-only exemption. With no `mintCall` the rule is inert.
+ */
+interface SessionKindStampedOptions extends SessionSourceScopeOptions {
+    /** Rule id, for running more than one instance. Default `session-kind-stamped`. */
+    readonly id?: string;
+    /** The method whose call mints a session, matched as `.<mintCall>(`. Unset or empty = inert. */
+    readonly mintCall?: string;
+    /** The session field every mint must stamp. Default `kind`. */
+    readonly field?: string;
+    /**
+     * Repo-relative files whose mints may stamp nothing because they provably can
+     * never mint for a principal that needs the field (a self-signup that only
+     * ever creates the default kind). Keep it short and write the proof next to
+     * each entry. Default: none.
+     */
+    readonly allowUnstamped?: readonly string[];
+    /** An example of the stamp, quoted in the message (e.g. a conditional spread). Optional. */
+    readonly stampExample?: string;
+    /** Appended to every message: a pointer to the project's own docs. */
+    readonly hint?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Every session mint stamps the principal's kind onto the session it writes.
+ *
+ * When the request pipeline reads the kind from the SESSION rather than the
+ * database, a session minted without it reads as whatever the reader defaults
+ * to. For a fence between two kinds of account that is a silent promotion of
+ * one into the other, and every gate stays green because nothing looks.
+ *
+ * The check, in order of precision:
+ *
+ * 1. A call whose arguments contain an object LITERAL must mention the field in
+ *    that literal. Each literal is checked on its own, so one stamped mint does
+ *    not excuse an unstamped one in the same file.
+ * 2. A call with no literal (options built elsewhere) falls back to the file:
+ *    the file must mention the field somewhere. Coarser, but no silent hole.
+ * 3. Otherwise the file must be on `allowUnstamped`.
+ *
+ * Residual gap, stated rather than hidden: a file that stamps the field on one
+ * delegated mint and forgets it on a second delegated mint passes clause 2.
+ */
+declare function createSessionKindStampedRule(options?: SessionKindStampedOptions): IMetaRule;
+
+/** One file that opens a door into a session, and where it leaves the caller. */
+interface SessionDoor {
+    /** Repo-relative path of the file. */
+    readonly file: string;
+    /** One of the keys of `landings`. */
+    readonly landing: string;
+    /** Why this landing is right for this door. Prose, read by whoever adds the next door. Must not be empty. */
+    readonly because: string;
+}
+/**
+ * Options for {@link createSessionLandingDeclaredRule}.
+ *
+ * Ported from Settly, which hardcoded the two door calls, its six doors and the
+ * three landings (`login-result`, which must return `Promise<ILoginResult>`,
+ * `reissue` and `staff-only`). All of them are options; with no `doorCalls` the
+ * rule is inert.
+ */
+interface SessionLandingDeclaredOptions extends SessionSourceScopeOptions {
+    /** Rule id, for running more than one instance. Default `session-landing-declared`. */
+    readonly id?: string;
+    /**
+     * The methods whose call opens a door into a session (the mint, and the gate
+     * in front of it), each matched as `.<name>(`. Empty (the default) = inert.
+     */
+    readonly doorCalls?: readonly string[];
+    /** Every door, declared. A file that calls a door method and is not here is reported. */
+    readonly doors?: readonly SessionDoor[];
+    /**
+     * The landings a door may declare, each mapped to the text a door with that
+     * landing must contain (the return type that carries the principal kind to the
+     * client, say), or `null` when the landing demands nothing of the source. A
+     * door whose landing is not a key here is reported. Default: none.
+     */
+    readonly landings?: Readonly<Record<string, string | null>>;
+    /** Appended to every message: a pointer to the project's own docs. */
+    readonly hint?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Every file that opens a door into a session declares where it leaves the
+ * caller, and a door that must hand the client the principal kind does.
+ *
+ * With two shells behind one sign-in, the client can only send an account to
+ * the right one if the response that ends the sign-in says which kind it is. A
+ * second door that finishes a sign-in from a different service can forget to,
+ * and nothing fails: the account signs in and lands in the wrong shell.
+ *
+ * The check is completeness first: a file that calls a door method and is not
+ * in `doors` fails the build until someone classifies it, which is what keeps
+ * the list an enumeration rather than a docblock nobody updates. Then each
+ * door's landing is checked against `landings`, and a declared door that no
+ * longer exists (or that `sourceGlobs` do not reach) is reported so the list
+ * cannot go stale.
+ */
+declare function createSessionLandingDeclaredRule(options?: SessionLandingDeclaredOptions): IMetaRule;
+
+/**
+ * Options for {@link createSessionMintCallersRule}.
+ *
+ * Ported from Settly's `establish-session-callers`, which hardcoded the method
+ * (`establishSession`), the gate (`beginOrEstablish`) and the five allowlisted
+ * files. All three are options here; with no `mintCall` the rule is inert.
+ */
+interface SessionMintCallersOptions extends SessionSourceScopeOptions {
+    /** Rule id, for running more than one instance. Default `session-mint-callers`. */
+    readonly id?: string;
+    /**
+     * The method whose call mints a session (sets the cookie, writes the store),
+     * matched as `.<mintCall>(`. Unset or empty = inert.
+     */
+    readonly mintCall?: string;
+    /**
+     * Repo-relative files that may call it: the method's own home, the gate in
+     * front of it, and flows with no gate to pass (signup, a re-issue to a caller
+     * who already holds a session). Matched exactly, so a same-named file in
+     * another directory is not allowed. Default: none.
+     */
+    readonly allowedCallers?: readonly string[];
+    /**
+     * The method a new sign-in entry point must route through instead (a second
+     * factor challenge, say), named in the message. Optional.
+     */
+    readonly gateCall?: string;
+    /** Appended to every message: a pointer to the project's own docs. */
+    readonly hint?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * The method that mints a session is callable only from an allowlist of files.
+ *
+ * A session minted straight from a sign-in entry point skips whatever the gate
+ * in front of the mint enforces (a second factor, an epoch capture), and nothing
+ * else fails: the new flow signs the user in and every test passes. The mint is
+ * the one door into a session, so the rule fences the door by caller.
+ */
+declare function createSessionMintCallersRule(options?: SessionMintCallersOptions): IMetaRule;
+
+export { type SessionDoor, type SessionEpochCapturedOptions, type SessionKindStampedOptions, type SessionLandingDeclaredOptions, type SessionMintCallersOptions, type SessionSourceScopeOptions, callArguments, createSessionEpochCapturedRule, createSessionKindStampedRule, createSessionLandingDeclaredRule, createSessionMintCallersRule };

package/dist/session.d.ts

@@ -0,0 +1,226 @@
+import { IMetaRule } from '@noctcore/harness';
+
+/**
+ * The source scope every session rule shares: which files are read, and which
+ * of them are left alone because they drive the seam directly (tests).
+ */
+interface SessionSourceScopeOptions {
+    /**
+     * Globs of the application source that can open a session, relative to the
+     * repo root. Empty (the default) makes the rule inert: it reads nothing and
+     * reports nothing. Point it at shipped code only; a lint-meta rule module that
+     * quotes the call in its own pattern is not a call site.
+     */
+    readonly sourceGlobs?: readonly string[];
+    /** Paths with any of these segments are skipped. Default `node_modules`, `.git`, `dist`, `.turbo`, `coverage`. */
+    readonly skipDirs?: readonly string[];
+    /**
+     * Files ending in any of these are skipped: tests drive the seam directly,
+     * including shapes production never produces. Default
+     * `['.spec.ts', '.spec.tsx', '.test.ts', '.test.tsx']`.
+     */
+    readonly excludeSuffixes?: readonly string[];
+}
+/**
+ * The argument text of each `.<method>(...)` call in `source`.
+ *
+ * Scanned by balancing parentheses rather than matched with a regex: an options
+ * object spans lines and holds its own braces and parens, and a non-greedy
+ * regex either stops early or runs on into the next call. A scanner that never
+ * finds the closing paren returns what it has, which is the fail-closed
+ * direction (more text to search, never less). `.<method>Something(` is not a
+ * call of `method`: only whitespace may sit between the name and the paren.
+ */
+declare function callArguments(source: string, method: string): string[];
+
+/**
+ * Options for {@link createSessionEpochCapturedRule}.
+ *
+ * Ported from Settly, which hardcoded the seam (`beginOrEstablish`), the field
+ * (`epoch`) and the seam's own file. With no `call` the rule is inert.
+ */
+interface SessionEpochCapturedOptions extends SessionSourceScopeOptions {
+    /** Rule id, for running more than one instance. Default `session-epoch-captured`. */
+    readonly id?: string;
+    /**
+     * The post-credential seam every sign-in passes through on its way to a
+     * session, matched as `.<call>(`. Unset or empty = inert.
+     */
+    readonly call?: string;
+    /** The argument every call must mention: the epoch captured before the credential was read. Default `epoch`. */
+    readonly field?: string;
+    /**
+     * Repo-relative files skipped outright: the seam's own home, which defines
+     * the method and may call itself without a captured value. Default: none.
+     */
+    readonly exempt?: readonly string[];
+    /** How the epoch is captured (e.g. `sessions.readEpoch(userId)`), quoted in the message. Optional. */
+    readonly captureCall?: string;
+    /** Appended to every message: a pointer to the project's own docs. */
+    readonly hint?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Every call into the sign-in seam passes the session epoch it captured before
+ * reading the credential.
+ *
+ * A revoke-all bumps a per-user epoch and a mint refuses to write a session
+ * under a stale one. Captured inside the mint, the fence covers the store write
+ * and nothing else: the whole credential check (a password hash verify, an
+ * OAuth token exchange) is a window in which a sign-in that already read the
+ * revoked state still mints a surviving session. So each entry point captures
+ * the epoch first and hands it to the seam, and this rule fails any call whose
+ * arguments never mention it.
+ */
+declare function createSessionEpochCapturedRule(options?: SessionEpochCapturedOptions): IMetaRule;
+
+/**
+ * Options for {@link createSessionKindStampedRule}.
+ *
+ * Ported from Settly, which hardcoded the mint (`establishSession`), the field
+ * (`kind`) and the one staff-only exemption. With no `mintCall` the rule is inert.
+ */
+interface SessionKindStampedOptions extends SessionSourceScopeOptions {
+    /** Rule id, for running more than one instance. Default `session-kind-stamped`. */
+    readonly id?: string;
+    /** The method whose call mints a session, matched as `.<mintCall>(`. Unset or empty = inert. */
+    readonly mintCall?: string;
+    /** The session field every mint must stamp. Default `kind`. */
+    readonly field?: string;
+    /**
+     * Repo-relative files whose mints may stamp nothing because they provably can
+     * never mint for a principal that needs the field (a self-signup that only
+     * ever creates the default kind). Keep it short and write the proof next to
+     * each entry. Default: none.
+     */
+    readonly allowUnstamped?: readonly string[];
+    /** An example of the stamp, quoted in the message (e.g. a conditional spread). Optional. */
+    readonly stampExample?: string;
+    /** Appended to every message: a pointer to the project's own docs. */
+    readonly hint?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Every session mint stamps the principal's kind onto the session it writes.
+ *
+ * When the request pipeline reads the kind from the SESSION rather than the
+ * database, a session minted without it reads as whatever the reader defaults
+ * to. For a fence between two kinds of account that is a silent promotion of
+ * one into the other, and every gate stays green because nothing looks.
+ *
+ * The check, in order of precision:
+ *
+ * 1. A call whose arguments contain an object LITERAL must mention the field in
+ *    that literal. Each literal is checked on its own, so one stamped mint does
+ *    not excuse an unstamped one in the same file.
+ * 2. A call with no literal (options built elsewhere) falls back to the file:
+ *    the file must mention the field somewhere. Coarser, but no silent hole.
+ * 3. Otherwise the file must be on `allowUnstamped`.
+ *
+ * Residual gap, stated rather than hidden: a file that stamps the field on one
+ * delegated mint and forgets it on a second delegated mint passes clause 2.
+ */
+declare function createSessionKindStampedRule(options?: SessionKindStampedOptions): IMetaRule;
+
+/** One file that opens a door into a session, and where it leaves the caller. */
+interface SessionDoor {
+    /** Repo-relative path of the file. */
+    readonly file: string;
+    /** One of the keys of `landings`. */
+    readonly landing: string;
+    /** Why this landing is right for this door. Prose, read by whoever adds the next door. Must not be empty. */
+    readonly because: string;
+}
+/**
+ * Options for {@link createSessionLandingDeclaredRule}.
+ *
+ * Ported from Settly, which hardcoded the two door calls, its six doors and the
+ * three landings (`login-result`, which must return `Promise<ILoginResult>`,
+ * `reissue` and `staff-only`). All of them are options; with no `doorCalls` the
+ * rule is inert.
+ */
+interface SessionLandingDeclaredOptions extends SessionSourceScopeOptions {
+    /** Rule id, for running more than one instance. Default `session-landing-declared`. */
+    readonly id?: string;
+    /**
+     * The methods whose call opens a door into a session (the mint, and the gate
+     * in front of it), each matched as `.<name>(`. Empty (the default) = inert.
+     */
+    readonly doorCalls?: readonly string[];
+    /** Every door, declared. A file that calls a door method and is not here is reported. */
+    readonly doors?: readonly SessionDoor[];
+    /**
+     * The landings a door may declare, each mapped to the text a door with that
+     * landing must contain (the return type that carries the principal kind to the
+     * client, say), or `null` when the landing demands nothing of the source. A
+     * door whose landing is not a key here is reported. Default: none.
+     */
+    readonly landings?: Readonly<Record<string, string | null>>;
+    /** Appended to every message: a pointer to the project's own docs. */
+    readonly hint?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Every file that opens a door into a session declares where it leaves the
+ * caller, and a door that must hand the client the principal kind does.
+ *
+ * With two shells behind one sign-in, the client can only send an account to
+ * the right one if the response that ends the sign-in says which kind it is. A
+ * second door that finishes a sign-in from a different service can forget to,
+ * and nothing fails: the account signs in and lands in the wrong shell.
+ *
+ * The check is completeness first: a file that calls a door method and is not
+ * in `doors` fails the build until someone classifies it, which is what keeps
+ * the list an enumeration rather than a docblock nobody updates. Then each
+ * door's landing is checked against `landings`, and a declared door that no
+ * longer exists (or that `sourceGlobs` do not reach) is reported so the list
+ * cannot go stale.
+ */
+declare function createSessionLandingDeclaredRule(options?: SessionLandingDeclaredOptions): IMetaRule;
+
+/**
+ * Options for {@link createSessionMintCallersRule}.
+ *
+ * Ported from Settly's `establish-session-callers`, which hardcoded the method
+ * (`establishSession`), the gate (`beginOrEstablish`) and the five allowlisted
+ * files. All three are options here; with no `mintCall` the rule is inert.
+ */
+interface SessionMintCallersOptions extends SessionSourceScopeOptions {
+    /** Rule id, for running more than one instance. Default `session-mint-callers`. */
+    readonly id?: string;
+    /**
+     * The method whose call mints a session (sets the cookie, writes the store),
+     * matched as `.<mintCall>(`. Unset or empty = inert.
+     */
+    readonly mintCall?: string;
+    /**
+     * Repo-relative files that may call it: the method's own home, the gate in
+     * front of it, and flows with no gate to pass (signup, a re-issue to a caller
+     * who already holds a session). Matched exactly, so a same-named file in
+     * another directory is not allowed. Default: none.
+     */
+    readonly allowedCallers?: readonly string[];
+    /**
+     * The method a new sign-in entry point must route through instead (a second
+     * factor challenge, say), named in the message. Optional.
+     */
+    readonly gateCall?: string;
+    /** Appended to every message: a pointer to the project's own docs. */
+    readonly hint?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * The method that mints a session is callable only from an allowlist of files.
+ *
+ * A session minted straight from a sign-in entry point skips whatever the gate
+ * in front of the mint enforces (a second factor, an epoch capture), and nothing
+ * else fails: the new flow signs the user in and every test passes. The mint is
+ * the one door into a session, so the rule fences the door by caller.
+ */
+declare function createSessionMintCallersRule(options?: SessionMintCallersOptions): IMetaRule;
+
+export { type SessionDoor, type SessionEpochCapturedOptions, type SessionKindStampedOptions, type SessionLandingDeclaredOptions, type SessionMintCallersOptions, type SessionSourceScopeOptions, callArguments, createSessionEpochCapturedRule, createSessionKindStampedRule, createSessionLandingDeclaredRule, createSessionMintCallersRule };