@naswerks/periscope 1.0.0

package/dist/identity/device-code.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The device-code fallback — for a box with no browser on it, which for this package is not an edge
+ * case but a deployment target.
+ *
+ * It is off unless explicitly configured, and it is never reached by falling back. Microsoft's
+ * guidance classes device code as a high-risk flow that phishing campaigns exploit and recommends
+ * that organisations block it (the Conditional Access authentication-flows documentation,
+ * https://learn.microsoft.com/entra/identity/conditional-access/concept-authentication-flows#device-code-flow);
+ * it is also exactly what workplace Conditional Access
+ * policies block, so a tenant refusing it outright is an expected outcome rather than a bug. A flow
+ * with that standing must be asked for by name — silently falling back to it when the loopback
+ * listener cannot bind would be the host quietly choosing the riskier option on the operator's
+ * behalf, at the moment they are least able to notice.
+ *
+ * And the trap that is invisible for weeks. A provider that tracks which protocol issued a token
+ * marks a refresh token obtained through device code as such, and a later non-device-code refresh
+ * against it fails with `AADSTS530036`; the provider's guidance is that such a token is unusable
+ * for good and should be deleted.
+ * The failure does not appear at sign-in; it appears the first time the token is refreshed, which
+ * for an unattended host is hours or weeks later and nowhere near the cause. So a device-code
+ * sign-in poisons the cache for any other flow: if this
+ * host ever switches a deployment back to loopback, the cached material must be discarded, not
+ * refreshed. `discardOnProtocolMismatch` is how that is decided rather than discovered.
+ */
+import type { Refusal } from '../core/refusal.js';
+import type { Result } from '../core/result.js';
+import type { IdentityConfig } from './config.js';
+/** Which flow minted the material this host holds. Recorded so the trap above is decidable. */
+export type AuthProtocol = 'loopback' | 'device-code';
+/**
+ * The error code the provider returns when a Conditional Access authentication-flows policy
+ * rejects a refresh. Named so a reader can search for it.
+ *
+ * It is not a cross-protocol error, and naming it as one names the wrong cause. `AADSTS530036` is
+ * not "you refreshed device-code material with a different flow". Microsoft's documentation
+ * describes it as a Conditional Access authentication-flows check refusing the refresh token, and
+ * because such a policy applies to every application the token is unusable for good and should be
+ * deleted. The mechanism is protocol tracking: a session established with device code stays marked
+ * through every later refresh, and the tenant's policy then rejects it, so the trigger is an
+ * administrator enabling a policy, not this host being reconfigured. Source:
+ * https://learn.microsoft.com/entra/identity/conditional-access/concept-authentication-flows#device-code-flow
+ *
+ * A cross-protocol name would be dangerous rather than merely inaccurate: it would imply the fix
+ * is to sign in again, which re-runs the same flow into the same policy, forever. And it is the
+ * policy Microsoft actively recommends: allow device code only where a documented case needs it
+ * and block it everywhere else
+ * (https://learn.microsoft.com/entra/identity/conditional-access/policy-block-authentication-flows).
+ * See `host/sign-in.ts` for the recovery
+ * this routes to.
+ */
+export declare const AUTH_FLOW_BLOCKED_ERROR = "AADSTS530036";
+/**
+ * Every provider code known to mean "a policy has blocked the flow this material was minted by".
+ * One today; a provider that reports the same condition under another code is added here, and
+ * only here: this file is the one place in the package that may know a provider's error codes.
+ */
+export declare const AUTH_FLOW_BLOCKED_CODES: readonly string[];
+export interface DeviceAuthorization {
+    readonly deviceCode: string;
+    readonly userCode: string;
+    readonly verificationUri: string;
+    readonly expiresAt: number;
+    readonly intervalMs: number;
+}
+/** The provider's answer to one poll. */
+export type DevicePollOutcome = {
+    readonly kind: 'pending';
+}
+/** The provider asked the caller to back off; the caller widens its interval by this much. */
+ | {
+    readonly kind: 'slow-down';
+    readonly intervalMs: number;
+} | {
+    readonly kind: 'ready';
+} | {
+    readonly kind: 'declined';
+    readonly refusal: Refusal;
+};
+/**
+ * Refuse the device-code flow unless it was turned on.
+ *
+ * Exported and total so the refusal is reachable in a test rather than being a branch nobody drives.
+ */
+export declare function requireDeviceCodeEnabled(config: IdentityConfig): Result<true>;
+export declare function deviceAuthorizationBody(config: IdentityConfig): string;
+export declare function devicePollBody(config: IdentityConfig, deviceCode: string): string;
+export declare function readDeviceAuthorization(status: number, body: unknown, nowMs: number): Result<DeviceAuthorization>;
+/**
+ * Read one poll response.
+ *
+ * `authorization_pending` and `slow_down` are not failures — they are the protocol working. Mapping
+ * them onto a refusal would end a sign-in that was proceeding normally.
+ */
+export declare function readDevicePoll(status: number, body: unknown, currentIntervalMs: number): DevicePollOutcome;
+/**
+ * Must cached material be discarded rather than refreshed, because this host was reconfigured?
+ *
+ * This is not the `AADSTS530036` guard. It detects one real but narrow
+ * case: the cache was minted by one flow and the host is now configured for the other, so a refresh
+ * would fail for a reason nobody would connect to a sign-in that happened weeks ago.
+ *
+ * It cannot fire on the policy case, which is the common one. When a tenant enables the
+ * authentication-flows policy, the host is still configured for device code and the cache was still
+ * minted by device code — `cached === configured`, so this returns `false` and nothing is discarded.
+ * A guard named for an error it is structurally unable to catch is worse than no guard, because it
+ * reads as coverage. The reactive path in `host/sign-in.ts` is what handles the policy case.
+ */
+export declare function discardOnProtocolMismatch(cached: AuthProtocol, configured: AuthProtocol): boolean;
+/**
+ * Does this provider error mean a Conditional Access authentication-flows policy has blocked this
+ * material permanently? Microsoft's documentation: "the token will never be usable and should be
+ * deleted."
+ */
+export declare function isAuthFlowBlocked(errorText: string): boolean;
+//# sourceMappingURL=device-code.d.ts.map

package/dist/identity/device-code.js

@@ -0,0 +1,134 @@
+import { refusal } from '../core/refusal.js';
+import { ok, refuse } from '../core/result.js';
+import { redactSecrets, secretsIn } from './token.js';
+/**
+ * The error code the provider returns when a Conditional Access authentication-flows policy
+ * rejects a refresh. Named so a reader can search for it.
+ *
+ * It is not a cross-protocol error, and naming it as one names the wrong cause. `AADSTS530036` is
+ * not "you refreshed device-code material with a different flow". Microsoft's documentation
+ * describes it as a Conditional Access authentication-flows check refusing the refresh token, and
+ * because such a policy applies to every application the token is unusable for good and should be
+ * deleted. The mechanism is protocol tracking: a session established with device code stays marked
+ * through every later refresh, and the tenant's policy then rejects it, so the trigger is an
+ * administrator enabling a policy, not this host being reconfigured. Source:
+ * https://learn.microsoft.com/entra/identity/conditional-access/concept-authentication-flows#device-code-flow
+ *
+ * A cross-protocol name would be dangerous rather than merely inaccurate: it would imply the fix
+ * is to sign in again, which re-runs the same flow into the same policy, forever. And it is the
+ * policy Microsoft actively recommends: allow device code only where a documented case needs it
+ * and block it everywhere else
+ * (https://learn.microsoft.com/entra/identity/conditional-access/policy-block-authentication-flows).
+ * See `host/sign-in.ts` for the recovery
+ * this routes to.
+ */
+export const AUTH_FLOW_BLOCKED_ERROR = 'AADSTS530036';
+/**
+ * Every provider code known to mean "a policy has blocked the flow this material was minted by".
+ * One today; a provider that reports the same condition under another code is added here, and
+ * only here: this file is the one place in the package that may know a provider's error codes.
+ */
+export const AUTH_FLOW_BLOCKED_CODES = [AUTH_FLOW_BLOCKED_ERROR];
+/**
+ * Refuse the device-code flow unless it was turned on.
+ *
+ * Exported and total so the refusal is reachable in a test rather than being a branch nobody drives.
+ */
+export function requireDeviceCodeEnabled(config) {
+    if (!config.deviceCodeEnabled) {
+        return refuse('device-code-not-enabled', 'the device-code flow is not enabled on this host; set PERISCOPE_IDENTITY_DEVICE_CODE=1 to allow it, and expect some tenants to refuse it by policy');
+    }
+    return ok(true);
+}
+export function deviceAuthorizationBody(config) {
+    const body = new URLSearchParams();
+    body.set('client_id', config.clientId);
+    body.set('scope', config.scopes.join(' '));
+    return body.toString();
+}
+export function devicePollBody(config, deviceCode) {
+    const body = new URLSearchParams();
+    // RFC 8628's grant type, urn-namespaced.
+    body.set('grant_type', 'urn:ietf:params:oauth:grant-type:device_code');
+    body.set('client_id', config.clientId);
+    body.set('device_code', deviceCode);
+    return body.toString();
+}
+export function readDeviceAuthorization(status, body, nowMs) {
+    const secrets = secretsIn(body);
+    if (typeof body !== 'object' || body === null) {
+        return refuse('device-code-declined', `the device authorization endpoint returned HTTP ${status} with no JSON body`);
+    }
+    const record = body;
+    if (status < 200 || status >= 300) {
+        const error = typeof record['error'] === 'string' ? record['error'] : `HTTP ${status}`;
+        return refuse('device-code-declined', redactSecrets(`the device authorization endpoint refused: ${error} — some tenants block this flow by policy`, secrets));
+    }
+    const deviceCode = record['device_code'];
+    const userCode = record['user_code'];
+    const verificationUri = record['verification_uri'] ?? record['verification_url'];
+    const expiresIn = Number(record['expires_in']);
+    const interval = Number(record['interval']);
+    if (typeof deviceCode !== 'string' || typeof userCode !== 'string' || typeof verificationUri !== 'string') {
+        return refuse('device-code-declined', 'the device authorization response is missing device_code, user_code or verification_uri');
+    }
+    if (!Number.isFinite(expiresIn) || expiresIn <= 0) {
+        return refuse('device-code-declined', 'the device authorization response carries no usable expires_in');
+    }
+    return ok({
+        deviceCode,
+        userCode,
+        verificationUri,
+        expiresAt: nowMs + expiresIn * 1000,
+        // RFC 8628 says default to 5 seconds when the provider does not state an interval.
+        intervalMs: (Number.isFinite(interval) && interval > 0 ? interval : 5) * 1000,
+    });
+}
+/**
+ * Read one poll response.
+ *
+ * `authorization_pending` and `slow_down` are not failures — they are the protocol working. Mapping
+ * them onto a refusal would end a sign-in that was proceeding normally.
+ */
+export function readDevicePoll(status, body, currentIntervalMs) {
+    if (status >= 200 && status < 300)
+        return { kind: 'ready' };
+    const record = typeof body === 'object' && body !== null ? body : {};
+    const error = typeof record['error'] === 'string' ? record['error'] : `http_${status}`;
+    if (error === 'authorization_pending')
+        return { kind: 'pending' };
+    if (error === 'slow_down')
+        return { kind: 'slow-down', intervalMs: currentIntervalMs + 5_000 };
+    const description = typeof record['error_description'] === 'string' ? record['error_description'] : null;
+    return {
+        kind: 'declined',
+        refusal: refusal('device-code-declined', redactSecrets(description === null
+            ? `the device-code sign-in ended: ${error}`
+            : `the device-code sign-in ended: ${error} — ${description}`, secretsIn(body))),
+    };
+}
+/**
+ * Must cached material be discarded rather than refreshed, because this host was reconfigured?
+ *
+ * This is not the `AADSTS530036` guard. It detects one real but narrow
+ * case: the cache was minted by one flow and the host is now configured for the other, so a refresh
+ * would fail for a reason nobody would connect to a sign-in that happened weeks ago.
+ *
+ * It cannot fire on the policy case, which is the common one. When a tenant enables the
+ * authentication-flows policy, the host is still configured for device code and the cache was still
+ * minted by device code — `cached === configured`, so this returns `false` and nothing is discarded.
+ * A guard named for an error it is structurally unable to catch is worse than no guard, because it
+ * reads as coverage. The reactive path in `host/sign-in.ts` is what handles the policy case.
+ */
+export function discardOnProtocolMismatch(cached, configured) {
+    return cached !== configured;
+}
+/**
+ * Does this provider error mean a Conditional Access authentication-flows policy has blocked this
+ * material permanently? Microsoft's documentation: "the token will never be usable and should be
+ * deleted."
+ */
+export function isAuthFlowBlocked(errorText) {
+    return AUTH_FLOW_BLOCKED_CODES.some((code) => errorText.includes(code));
+}
+//# sourceMappingURL=device-code.js.map

package/dist/identity/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Identity — signing a real user in, holding what that produced, and presenting it.
+ *
+ * Every module behind this barrel is pure. The two impure halves live in `host/`
+ * (`token-cache.ts` writes the file, `loopback.ts` opens the port), which is where this package
+ * confines anything that touches the machine. That split is the same one the gate uses, and it is
+ * what makes the awkward branches — a malformed cache, a callback with the wrong `state`, a
+ * filesystem that ignores modes — drivable without a machine in that state.
+ *
+ * Nothing here names a provider. The authority, client and endpoints are configuration, and the
+ * flows are RFC 6749 / 7636 / 8628 as written. Any one commercial provider is a configuration of
+ * this, not the shape of it — which is what lets somebody point this at their own provider and
+ * have it work.
+ */
+export type { IdentityConfig, IdentityEndpoints, IdentityPosture } from './config.js';
+export { DEFAULT_SCOPES, discoveryUrl, identityPosture, readDiscoveryDocument, readIdentityConfig, } from './config.js';
+export type { Pkce } from './pkce.js';
+export { CODE_CHALLENGE_METHOD, challengeFor, createPkce, createState, randomUrlSafe, requireS256, stateMatches, } from './pkce.js';
+export type { AuthorizationCallback, AuthorizationRequest } from './authorize.js';
+export { CALLBACK_PAGE, buildAuthorizationUrl, readAuthorizationCallback, redirectUriFor, } from './authorize.js';
+export type { TokenSet } from './token.js';
+export { EXPIRY_SKEW_MS, authorizationValue, codeExchangeBody, isFresh, readTokenResponse, redactSecrets, refreshBody, secretsIn, } from './token.js';
+export type { CredentialModeOutcome, ModeEnforcement } from './mode.js';
+export { CREDENTIAL_MODE, classifyCredentialMode, classifyProbeReadings, isWiderThan, toOctal, } from './mode.js';
+export type { AuthProtocol, DeviceAuthorization, DevicePollOutcome } from './device-code.js';
+export { AUTH_FLOW_BLOCKED_CODES, AUTH_FLOW_BLOCKED_ERROR, deviceAuthorizationBody, devicePollBody, discardOnProtocolMismatch, isAuthFlowBlocked, readDeviceAuthorization, readDevicePoll, requireDeviceCodeEnabled, } from './device-code.js';
+export type { CachedTokens, TokenStore } from './store.js';
+export { readCachedTokens } from './store.js';
+export type { TokenCredentialOptions, TokenRefresher } from './credential.js';
+export { AUTHORIZATION_HEADER, TokenCredential } from './credential.js';
+export type { PairedCredentialFile, PairedCredentialStore } from './paired-credential.js';
+export { PairedHostCredential, readPairedCredentialFile } from './paired-credential.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/identity/index.js

@@ -0,0 +1,10 @@
+export { DEFAULT_SCOPES, discoveryUrl, identityPosture, readDiscoveryDocument, readIdentityConfig, } from './config.js';
+export { CODE_CHALLENGE_METHOD, challengeFor, createPkce, createState, randomUrlSafe, requireS256, stateMatches, } from './pkce.js';
+export { CALLBACK_PAGE, buildAuthorizationUrl, readAuthorizationCallback, redirectUriFor, } from './authorize.js';
+export { EXPIRY_SKEW_MS, authorizationValue, codeExchangeBody, isFresh, readTokenResponse, redactSecrets, refreshBody, secretsIn, } from './token.js';
+export { CREDENTIAL_MODE, classifyCredentialMode, classifyProbeReadings, isWiderThan, toOctal, } from './mode.js';
+export { AUTH_FLOW_BLOCKED_CODES, AUTH_FLOW_BLOCKED_ERROR, deviceAuthorizationBody, devicePollBody, discardOnProtocolMismatch, isAuthFlowBlocked, readDeviceAuthorization, readDevicePoll, requireDeviceCodeEnabled, } from './device-code.js';
+export { readCachedTokens } from './store.js';
+export { AUTHORIZATION_HEADER, TokenCredential } from './credential.js';
+export { PairedHostCredential, readPairedCredentialFile } from './paired-credential.js';
+//# sourceMappingURL=index.js.map

package/dist/identity/mode.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Whether the token file on disk is actually as private as requested — decided here, purely, so
+ * every branch can be driven on any platform.
+ *
+ * The defect, observed on win32 rather than reasoned. On win32, `node` accepts a `0o600` mode and
+ * does nothing with it: writing with `{mode: 0o600}` and then `chmod`ing to `0o600` both leave
+ * `statSync().mode & 0o777` reading `0o666`, and a deliberately world-readable `0o666` file reads
+ * exactly the same. So on Windows a restricted token file and an unrestricted one are
+ * indistinguishable through the only API available.
+ *
+ * That makes the obvious implementation wrong in both directions, which is why this is a module and
+ * not an `if`:
+ *
+ *   - Verify literally (`observed === 0o600`) and the host refuses every write on Windows — it
+ *     would be unusable there.
+ *   - Relax it to "not world-writable" and the check passes vacuously on Windows while proving
+ *     nothing at all — a green that reads as evidence.
+ *
+ * So the third answer is the only honest one: where modes are enforced, verify and refuse if the
+ * file came out wider than asked. Where they are not, say so by name as a degrade. A degrade is
+ * a named outcome, never a silent pass — and "this could not be confirmed" is a fact an operator
+ * can act on, while a checkmark that means nothing is not.
+ *
+ * Enforcement is measured, not assumed from `process.platform`. The caller probes it (see
+ * `host/token-cache.ts`) and passes the answer in. A platform list would be a guess that ages;
+ * WSL, a POSIX filesystem mounted on Windows, or a future runtime that maps modes onto ACLs would
+ * each make the guess wrong in the direction that matters.
+ *
+ * And the measurement has an inconclusive state, which is why this is a three-way enum and not a
+ * boolean. A probe that reports "not enforced" is only worth anything if it could have reported
+ * something else. On win32, `chmod 0444` does read back as `444`, so the write bit is real even
+ * though the read/group/other bits are fabricated as `6`. That gives the probe a positive control
+ * — it can demonstrate it observes something before it claims it cannot observe privacy.
+ * Without that, "unenforced" and "my probe is broken" are the same answer, and an instrument with
+ * no inconclusive state reports confidence it has not earned.
+ */
+import type { Refusal } from '../core/refusal.js';
+/** The mode credential material is written with, everywhere. */
+export declare const CREDENTIAL_MODE = 384;
+/** What the filesystem was measured to do with a mode. */
+export type ModeEnforcement = 
+/** POSIX modes are honoured: what was asked for is what came back, and wide differs from narrow. */
+'enforced'
+/**
+ * Measured, and the answer is that only the write bit survives — the win32 shape. `0600` and
+ * `0666` are indistinguishable, so privacy cannot be confirmed; but `0444` reads back as `444`,
+ * so the instrument is live and this is a real finding rather than a dead probe.
+ */
+ | 'write-bit-only'
+/**
+ * Inconclusive. No mode change was observable at all, not even clearing the write bit. The
+ * probe cannot distinguish "this filesystem records nothing" from "this probe is broken", and
+ * saying so is the only honest option.
+ */
+ | 'unobservable';
+export type CredentialModeOutcome = 
+/** Modes are enforced here and the file is exactly as private as requested. */
+{
+    readonly kind: 'verified';
+    readonly observed: number;
+}
+/** Modes are enforced here and the file is readable or writable by more than its owner. */
+ | {
+    readonly kind: 'too-wide';
+    readonly observed: number;
+    readonly refusal: Refusal;
+}
+/** Not a failure: privacy is unconfirmable here, and that was measured rather than assumed. */
+ | {
+    readonly kind: 'unenforced';
+    readonly observed: number;
+    readonly refusal: Refusal;
+}
+/** Not even a measurement: the instrument could observe nothing. Worth investigating. */
+ | {
+    readonly kind: 'unobservable';
+    readonly observed: number;
+    readonly refusal: Refusal;
+};
+/** Is any permission bit set that was not requested? */
+export declare function isWiderThan(observed: number, requested: number): boolean;
+/**
+ * Decide what three probe readings mean. Pure, so the shapes this machine cannot produce are still
+ * drivable.
+ *
+ * This function exists because the obvious control is vacuous. Without the `0444` reading, on
+ * win32 a probe that runs the control and a probe that merely assumes its answer both report
+ * `write-bit-only`, so nothing on that machine can tell them apart. What is uniquely lost is the
+ * ability to distinguish a filesystem that records only the write bit from one that records
+ * nothing — and that difference only shows up on a filesystem a win32 machine cannot produce on
+ * demand. Stating the readings as data is what makes it testable at all.
+ *
+ *   narrow    what `stat` reported after asking for `requested` (0600)
+ *   wide      what it reported after asking for 0666
+ *   readOnly  what it reported after clearing the write bit (0444) — the positive control
+ */
+export declare function classifyProbeReadings(narrow: number, wide: number, readOnly: number, requested?: number): ModeEnforcement;
+/**
+ * Classify what a verify-after-write actually found.
+ *
+ * `enforcement` is the measured answer to "what does this filesystem do with a mode at all".
+ */
+export declare function classifyCredentialMode(observed: number, enforcement: ModeEnforcement, requested?: number): CredentialModeOutcome;
+/** `0o600`, for a message a human reads. */
+export declare function toOctal(mode: number): string;
+//# sourceMappingURL=mode.d.ts.map

package/dist/identity/mode.js

@@ -0,0 +1,69 @@
+import { refusal } from '../core/refusal.js';
+/** The mode credential material is written with, everywhere. */
+export const CREDENTIAL_MODE = 0o600;
+const PERMISSION_BITS = 0o777;
+/** Is any permission bit set that was not requested? */
+export function isWiderThan(observed, requested) {
+    return (observed & ~requested & PERMISSION_BITS) !== 0;
+}
+/**
+ * Decide what three probe readings mean. Pure, so the shapes this machine cannot produce are still
+ * drivable.
+ *
+ * This function exists because the obvious control is vacuous. Without the `0444` reading, on
+ * win32 a probe that runs the control and a probe that merely assumes its answer both report
+ * `write-bit-only`, so nothing on that machine can tell them apart. What is uniquely lost is the
+ * ability to distinguish a filesystem that records only the write bit from one that records
+ * nothing — and that difference only shows up on a filesystem a win32 machine cannot produce on
+ * demand. Stating the readings as data is what makes it testable at all.
+ *
+ *   narrow    what `stat` reported after asking for `requested` (0600)
+ *   wide      what it reported after asking for 0666
+ *   readOnly  what it reported after clearing the write bit (0444) — the positive control
+ */
+export function classifyProbeReadings(narrow, wide, readOnly, requested = CREDENTIAL_MODE) {
+    const n = narrow & PERMISSION_BITS;
+    const w = wide & PERMISSION_BITS;
+    const r = readOnly & PERMISSION_BITS;
+    // Full POSIX: what was asked for came back, and asking for something wider changed the answer.
+    if (n === (requested & PERMISSION_BITS) && n !== w)
+        return 'enforced';
+    // Privacy is unconfirmable. Before saying so, the instrument must have shown it observes
+    // something — otherwise "unenforced" is indistinguishable from a dead probe.
+    return r !== w ? 'write-bit-only' : 'unobservable';
+}
+/**
+ * Classify what a verify-after-write actually found.
+ *
+ * `enforcement` is the measured answer to "what does this filesystem do with a mode at all".
+ */
+export function classifyCredentialMode(observed, enforcement, requested = CREDENTIAL_MODE) {
+    const bits = observed & PERMISSION_BITS;
+    if (enforcement === 'unobservable') {
+        return {
+            kind: 'unobservable',
+            observed: bits,
+            refusal: refusal('credential-mode-unobservable', `mode ${toOctal(requested)} was requested and this filesystem reported no observable mode change of any kind — not even clearing the write bit — so nothing at all can be said about the token file's permissions here; this is an inconclusive instrument rather than a finding about privacy`),
+        };
+    }
+    if (enforcement === 'write-bit-only') {
+        return {
+            kind: 'unenforced',
+            observed: bits,
+            refusal: refusal('credential-mode-unenforced', `mode ${toOctal(requested)} was requested and this filesystem records only the write bit (it reports ${toOctal(bits)} here, and cannot distinguish owner-only from world-readable), so the token file's privacy cannot be confirmed — it is protected by the gate's credential-path denial and by the OS account, not by this mode. The probe did observe a mode change when the write bit was cleared, so this is a measurement rather than a dead check`),
+        };
+    }
+    if (isWiderThan(bits, requested)) {
+        return {
+            kind: 'too-wide',
+            observed: bits,
+            refusal: refusal('credential-mode-too-wide', `the token file was written with mode ${toOctal(bits)} after ${toOctal(requested)} was requested, so it is readable or writable by more than its owner`),
+        };
+    }
+    return { kind: 'verified', observed: bits };
+}
+/** `0o600`, for a message a human reads. */
+export function toOctal(mode) {
+    return `0${(mode & PERMISSION_BITS).toString(8)}`;
+}
+//# sourceMappingURL=mode.js.map

package/dist/identity/paired-credential.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The paired-host credential — the durable identity a machine holds after `periscope pair`.
+ *
+ * The shape and its validation live here, not with the filesystem — the same split `store.ts`
+ * states for the token cache, for the same reason: `host/` may import this, and this may never
+ * import `host/`.
+ *
+ * This is not the OIDC token and not the RFC 8628 `device-code` flow, and the noun is chosen to
+ * keep the three apart. A paired credential is an opaque controller-minted bearer
+ * (`p1.<hostId>.<secret>`): it never expires on a clock, never refreshes, and dies only when the
+ * controller revokes it — at which point the upgrade answers 401 and the host's terminal path
+ * names it. That is what makes it survive the idle window after which a provider may let an OIDC
+ * refresh token lapse.
+ *
+ * It carries no user, and cannot. The controller derives the acting user from its own registry
+ * row; a host presenting this credential asserts nothing about who it acts for, which is the whole
+ * design — nothing in this file could smuggle an identity claim even by mistake, because there is
+ * no field to put one in.
+ */
+import type { Authorization, ControllerCredential } from '../control/credential.js';
+import type { Result } from '../core/result.js';
+/** The persisted record — what `periscope pair` writes and the daemon reads. */
+export interface PairedCredentialFile {
+    /** The host id the credential names. The daemon announces this id in `link_hello` — the
+     * controller refuses a hello naming anything else, so the file's copy is load-bearing. */
+    readonly hostId: string;
+    /** The full opaque credential, exactly as the controller minted it. */
+    readonly credential: string;
+}
+/** The port the pair verb writes through and the daemon reads through — an interface for the same
+ * reason `TokenStore` is one: every malformed-file branch is drivable without a disk. */
+export interface PairedCredentialStore {
+    read(): Result<PairedCredentialFile>;
+    write(file: PairedCredentialFile): Result<unknown>;
+}
+/** Validate a parsed file into the shape the daemon relies on. */
+export declare function readPairedCredentialFile(parsed: unknown): Result<PairedCredentialFile>;
+/**
+ * The `ControllerCredential` a paired host presents — on the link, the decision POST and the bulk
+ * POST alike, through the one spread point in the composition root.
+ *
+ * No refresh, no expiry, no reporter, and each absence is the design: the credential is a stable
+ * secret whose validity lives server-side, so there is exactly one outcome here and nothing to
+ * distinguish. Revocation surfaces as the controller's 401, which the link already classifies as
+ * terminal `link-unauthorized` — this class cannot see it coming and must not pretend to.
+ */
+export declare class PairedHostCredential implements ControllerCredential {
+    #private;
+    constructor(file: PairedCredentialFile);
+    authorize(): Promise<Result<Authorization>>;
+}
+//# sourceMappingURL=paired-credential.d.ts.map

package/dist/identity/paired-credential.js

@@ -0,0 +1,43 @@
+import { ok, refuse } from '../core/result.js';
+import { AUTHORIZATION_HEADER } from './credential.js';
+/** Validate a parsed file into the shape the daemon relies on. */
+export function readPairedCredentialFile(parsed) {
+    if (typeof parsed !== 'object' || parsed === null) {
+        return refuse('credential-cache-unreadable', 'the paired credential file is not a JSON object');
+    }
+    const record = parsed;
+    const hostId = record['hostId'];
+    const credential = record['credential'];
+    if (typeof hostId !== 'string' || hostId === '') {
+        return refuse('credential-cache-unreadable', 'the paired credential file names no hostId');
+    }
+    if (typeof credential !== 'string' || credential === '') {
+        return refuse('credential-cache-unreadable', 'the paired credential file carries no credential');
+    }
+    // The credential embeds the host id it speaks for; a file whose two copies disagree would make
+    // this host announce one identity and authenticate as another — the exact mismatch the
+    // controller's hello binding exists to refuse. Caught here, where the fix (re-pair) is printable.
+    if (!credential.startsWith(`p1.${hostId}.`)) {
+        return refuse('credential-cache-unreadable', 'the paired credential does not match the hostId beside it — the file is corrupt; run: periscope pair <code>');
+    }
+    return ok({ hostId, credential });
+}
+/**
+ * The `ControllerCredential` a paired host presents — on the link, the decision POST and the bulk
+ * POST alike, through the one spread point in the composition root.
+ *
+ * No refresh, no expiry, no reporter, and each absence is the design: the credential is a stable
+ * secret whose validity lives server-side, so there is exactly one outcome here and nothing to
+ * distinguish. Revocation surfaces as the controller's 401, which the link already classifies as
+ * terminal `link-unauthorized` — this class cannot see it coming and must not pretend to.
+ */
+export class PairedHostCredential {
+    #value;
+    constructor(file) {
+        this.#value = `Bearer ${file.credential}`;
+    }
+    authorize() {
+        return Promise.resolve(ok({ header: AUTHORIZATION_HEADER, value: this.#value }));
+    }
+}
+//# sourceMappingURL=paired-credential.js.map

package/dist/identity/pkce.d.ts

@@ -0,0 +1,50 @@
+import type { Result } from '../core/result.js';
+/**
+ * The only challenge method this host will use.
+ *
+ * RFC 7636 also defines `plain`, where the challenge is the verifier. This host refuses it rather
+ * than merely not offering it — an unused branch is one a later reader restores on a compatibility
+ * report, and `plain` gives away the whole property to anyone who can observe the authorization
+ * request.
+ */
+export declare const CODE_CHALLENGE_METHOD = "S256";
+export interface Pkce {
+    readonly verifier: string;
+    readonly challenge: string;
+    readonly method: typeof CODE_CHALLENGE_METHOD;
+}
+/**
+ * A cryptographically random, URL-safe string.
+ *
+ * `randomBytes`, never `Math.random`. `Math.random` is seeded, predictable and explicitly not for
+ * this; a predictable verifier or state defeats the property entirely while looking identical in
+ * every test.
+ */
+export declare function randomUrlSafe(bytes?: number): string;
+/** A fresh verifier and its S256 challenge. */
+export declare function createPkce(): Pkce;
+/** The S256 challenge for a verifier: base64url(SHA-256(ascii(verifier))). */
+export declare function challengeFor(verifier: string): string;
+/**
+ * The `state` value for one authorization request.
+ *
+ * Same entropy source as the verifier and deliberately a separate value — reusing the verifier as
+ * state would put it in a URL the browser and the provider both log, and the verifier is the one
+ * that must never leave this process until the token exchange.
+ */
+export declare function createState(): string;
+/**
+ * Refuse a challenge method this host will not use.
+ *
+ * Exported so the refusal is reachable and testable, rather than being an `if` nobody can drive.
+ */
+export declare function requireS256(method: string): Result<typeof CODE_CHALLENGE_METHOD>;
+/**
+ * Compare two `state` values without leaking their contents through timing.
+ *
+ * The length check is separate and deliberate: `timingSafeEqual` throws on unequal lengths, so
+ * comparing lengths first is required rather than an optimisation. It leaks the length and nothing
+ * else, which is the standard accepted residual.
+ */
+export declare function stateMatches(expected: string, received: string): boolean;
+//# sourceMappingURL=pkce.d.ts.map