refactor: simplify authorization boundaries

This commit is contained in:
morluto
2026-07-18 05:49:14 +00:00
parent b537ebfa34
commit 2e5b44365f
59 changed files with 381 additions and 6286 deletions
+97 -92
View File
@@ -107,6 +107,26 @@ const isNotFound = (error: unknown): boolean =>
const errorReason = (error: unknown): PermissionPathError["reason"] =>
isNotFound(error) ? "not_found" : "io";
interface PermissionEvaluationOptions {
readonly elicitationSupported?: boolean;
readonly restartRequired?: boolean;
}
interface CanonicalPermissionDecision {
readonly decision: Extract<PermissionDecision, { readonly allowed: true }>;
readonly owner: PermissionAuthority;
readonly request: PermissionRequest;
}
type AuthorizedPermission = PermissionDecision & {
readonly allowed: true;
readonly request: PermissionRequest;
};
type PermissionAuthorizationResult = Promise<
Result<AuthorizedPermission, PermissionPathError | PermissionRequiredError>
>;
/** Stateful owner for permission evaluation, consumption, reload, and revoke. */
export class PermissionAuthority {
private policy: PermissionPolicy;
@@ -132,42 +152,37 @@ export class PermissionAuthority {
async authorize(
request: PermissionRequest,
access: "read" | "write",
options: {
readonly elicitationSupported?: boolean;
readonly restartRequired?: boolean;
} = {},
): Promise<
Result<
PermissionDecision & {
readonly allowed: true;
readonly request: PermissionRequest;
},
PermissionPathError | PermissionRequiredError
>
> {
const canonical = await canonicalizePermissionRequest(request, access);
if (!canonical.ok) return canonical;
const evaluated = this.evaluateCanonical(canonical.value, options);
options: PermissionEvaluationOptions = {},
): PermissionAuthorizationResult {
const evaluated = await this.evaluateRequest(request, access, options);
if (!evaluated.ok) return evaluated;
const { decision, owner } = evaluated.value;
const { decision, owner, request: canonicalRequest } = evaluated.value;
owner.policy = consumePermission(owner.policy, decision);
return ok({ ...decision, request: canonical.value });
return ok({ ...decision, request: canonicalRequest });
}
/** Dry-run the exact shared evaluation without consuming a once grant. */
async explain(
request: PermissionRequest,
access: "read" | "write",
options: {
readonly elicitationSupported?: boolean;
readonly restartRequired?: boolean;
} = {},
options: PermissionEvaluationOptions = {},
): PermissionAuthorizationResult {
const evaluated = await this.evaluateRequest(request, access, options);
return evaluated.ok
? ok({
...evaluated.value.decision,
request: evaluated.value.request,
})
: evaluated;
}
private async evaluateRequest(
request: PermissionRequest,
access: "read" | "write",
options: PermissionEvaluationOptions,
): Promise<
Result<
PermissionDecision & {
readonly allowed: true;
readonly request: PermissionRequest;
},
CanonicalPermissionDecision,
PermissionPathError | PermissionRequiredError
>
> {
@@ -175,7 +190,7 @@ export class PermissionAuthority {
if (!canonical.ok) return canonical;
const evaluated = this.evaluateCanonical(canonical.value, options);
return evaluated.ok
? ok({ ...evaluated.value.decision, request: canonical.value })
? ok({ ...evaluated.value, request: canonical.value })
: evaluated;
}
@@ -222,10 +237,7 @@ export class PermissionAuthority {
private evaluateCanonical(
request: PermissionRequest,
options: {
readonly elicitationSupported?: boolean;
readonly restartRequired?: boolean;
},
options: PermissionEvaluationOptions,
): Result<
{
readonly decision: Extract<
@@ -270,51 +282,33 @@ export class PermissionAuthority {
async replaceProjectGrants(
grants: readonly PermissionGrant[],
): Promise<Result<null, PermissionPathError>> {
let candidate: PermissionPolicy = {
...this.policy,
grants: this.policy.grants.filter(
({ lifetime }) => lifetime !== "project",
),
};
for (const grant of grants) {
const canonical = await canonicalizeGrant(grant);
if (!canonical.ok) return canonical;
const added = grantPermission(candidate, canonical.value);
if (!added.ok)
return err(
new PermissionPathError(grant.grant_id, "io", {
cause: added.error,
}),
);
candidate = added.value;
}
this.policy = candidate;
return ok(null);
return this.replaceGrants(grants, "project");
}
/** Replace grants derived from the currently loaded administrator ceiling. */
async replaceAdministratorGrants(
grants: readonly PermissionGrant[],
): Promise<Result<null, PermissionPathError>> {
let candidate: PermissionPolicy = {
...this.policy,
grants: this.policy.grants.filter(
({ lifetime }) => lifetime !== "administrator",
),
};
for (const grant of grants) {
const canonical = await canonicalizeGrant(grant);
if (!canonical.ok) return canonical;
const added = grantPermission(candidate, canonical.value);
if (!added.ok)
return err(
new PermissionPathError(grant.grant_id, "io", {
cause: added.error,
}),
);
candidate = added.value;
}
this.policy = candidate;
return this.replaceGrants(grants, "administrator");
}
private async replaceGrants(
grants: readonly PermissionGrant[],
lifetime: "administrator" | "project",
): Promise<Result<null, PermissionPathError>> {
const canonical = await canonicalizeGrants(grants);
if (!canonical.ok) return canonical;
const replaced = addGrantsToPolicy(
{
...this.policy,
grants: this.policy.grants.filter(
(grant) => grant.lifetime !== lifetime,
),
},
canonical.value,
);
if (!replaced.ok) return replaced;
this.policy = replaced.value;
return ok(null);
}
@@ -328,33 +322,21 @@ export class PermissionAuthority {
configuration.ceilings,
);
if (!ceilings.ok) return ceilings;
const grants: PermissionGrant[] = [];
for (const grant of [
const grants = await canonicalizeGrants([
...configuration.administratorGrants,
...configuration.projectGrants,
]) {
const canonical = await canonicalizeGrant(grant);
if (!canonical.ok) return canonical;
grants.push(canonical.value);
}
let candidate: PermissionPolicy = {
]);
if (!grants.ok) return grants;
const candidate: PermissionPolicy = {
...reloadPermissionCeilings(this.policy, ceilings.value),
grants: this.policy.grants.filter(
({ lifetime }) =>
lifetime !== "administrator" && lifetime !== "project",
),
};
for (const grant of grants) {
const added = grantPermission(candidate, grant);
if (!added.ok)
return err(
new PermissionPathError(grant.grant_id, "io", {
cause: added.error,
}),
);
candidate = added.value;
}
this.policy = candidate;
const replaced = addGrantsToPolicy(candidate, grants.value);
if (!replaced.ok) return replaced;
this.policy = replaced.value;
return ok(null);
}
@@ -376,18 +358,41 @@ export const createPermissionAuthority = async (
): Promise<Result<PermissionAuthority, PermissionPathError>> => {
const canonical = await canonicalizePermissionCeilings(ceilings);
if (!canonical.ok) return canonical;
let policy = createPermissionPolicy(canonical.value);
const canonicalGrants = await canonicalizeGrants(grants);
if (!canonicalGrants.ok) return canonicalGrants;
const policy = addGrantsToPolicy(
createPermissionPolicy(canonical.value),
canonicalGrants.value,
);
return policy.ok ? ok(new PermissionAuthority(policy.value)) : policy;
};
const canonicalizeGrants = async (
grants: readonly PermissionGrant[],
): Promise<Result<readonly PermissionGrant[], PermissionPathError>> => {
const canonical: PermissionGrant[] = [];
for (const grant of grants) {
const canonicalGrant = await canonicalizeGrant(grant);
if (!canonicalGrant.ok) return canonicalGrant;
const added = grantPermission(policy, canonicalGrant.value);
canonical.push(canonicalGrant.value);
}
return ok(canonical);
};
const addGrantsToPolicy = (
initial: PermissionPolicy,
grants: readonly PermissionGrant[],
): Result<PermissionPolicy, PermissionPathError> => {
let policy = initial;
for (const grant of grants) {
const added = grantPermission(policy, grant);
if (!added.ok)
return err(
new PermissionPathError(grant.grant_id, "io", { cause: added.error }),
);
policy = added.value;
}
return ok(new PermissionAuthority(policy));
return ok(policy);
};
const canonicalizeGrant = async (
-8
View File
@@ -21,7 +21,6 @@ export interface WindowsCapabilityDependencies {
probeSymlinkCreation(): Promise<WindowsCapabilityOutcome>;
probeNoFollowOpen(): WindowsCapabilityOutcome;
probePrivateAcl(): WindowsCapabilityOutcome;
probeNativeAuthority(): WindowsCapabilityOutcome;
probeUnixDomainSocket(): WindowsCapabilityOutcome;
probePty(): Promise<ProcessCaptureCapability>;
}
@@ -34,7 +33,6 @@ export interface WindowsCapabilityReport {
symlink_creation: WindowsCapabilityOutcome;
no_follow_open: WindowsCapabilityOutcome;
private_acl: WindowsCapabilityOutcome;
native_authority: WindowsCapabilityOutcome;
unix_domain_socket: WindowsCapabilityOutcome;
pty: WindowsCapabilityOutcome;
}>;
@@ -55,7 +53,6 @@ export const probeWindowsCapabilities = async (
symlink_creation: symlinkCreation,
no_follow_open: dependencies.probeNoFollowOpen(),
private_acl: dependencies.probePrivateAcl(),
native_authority: dependencies.probeNativeAuthority(),
unix_domain_socket: dependencies.probeUnixDomainSocket(),
pty: {
available: pty.available,
@@ -75,11 +72,6 @@ const systemDependencies = (): WindowsCapabilityDependencies => ({
available: false,
reason: "Windows ACL enforcement is not implemented by this REA build",
}),
probeNativeAuthority: () => ({
available: false,
reason:
"Windows native authority package is not implemented by this REA build",
}),
probeUnixDomainSocket: () =>
process.platform === "win32"
? {
File diff suppressed because it is too large Load Diff
@@ -1,401 +0,0 @@
import { createHash } from "node:crypto";
import { readFile, realpath } from "node:fs/promises";
import { createRequire } from "node:module";
import { win32 } from "node:path";
import { z } from "zod";
import { PACKAGE_METADATA } from "../generatedPackageMetadata.js";
import { err, ok, type Result } from "../domain/result.js";
import {
WindowsNativeAuthorityError,
type WindowsNativeAuthorityBackend,
type WindowsNativeAuthorityIdentity,
} from "./WindowsNativeAuthority.js";
const BACKEND_EXPORTS = [
"admitDirectory",
"admitFile",
"createPrivateRoot",
"identity",
"spawnOwnedProcess",
] as const;
const identitySchema = z.strictObject({
packageName: z.string().min(1),
packageVersion: z.string().min(1),
contractVersion: z.number().int().positive(),
nodeApiVersion: z.number().int().positive(),
artifactSha256: z.string().regex(/^[0-9a-f]{64}$/u),
});
const packageManifestSchema = z.object({
name: z.string().min(1),
version: z.string().min(1),
os: z.tuple([z.literal("win32")]),
cpu: z.tuple([z.literal("x64")]),
scripts: z.undefined().optional(),
reaNativeAuthority: z.strictObject({
contractVersion: z.number().int().positive(),
nodeApiVersion: z.number().int().positive(),
artifact: z.string().regex(/^[^\\/]+\.node$/u),
artifactSha256: z.string().regex(/^[0-9a-f]{64}$/u),
exports: z.tuple([
z.literal("admitDirectory"),
z.literal("admitFile"),
z.literal("createPrivateRoot"),
z.literal("identity"),
z.literal("spawnOwnedProcess"),
]),
}),
});
/** Release-generated identity required before the Windows addon can load. */
export interface WindowsNativeAuthorityPackageCommitment {
readonly packageName: string;
readonly packageVersion: string;
readonly contractVersion: number;
readonly nodeApiVersion: number;
readonly artifactSha256: string | null;
}
/** Injectable Node package-loading seam used by the production loader. */
export interface WindowsNativeAuthorityLoadHost {
readonly platform: NodeJS.Platform;
readonly architecture: string;
readonly nodeApiVersion: number | null;
resolve(packageName: string): string;
resolveManifest(packageName: string): string;
canonicalize(path: string): Promise<string>;
read(path: string): Promise<Uint8Array>;
cached(path: string): unknown | undefined;
load(path: string): unknown;
}
interface LoadedBackend {
readonly backend: LoadedWindowsNativeBackend;
readonly canonicalPath: string;
readonly identity: WindowsNativeAuthorityIdentity;
}
type LoadedWindowsNativeBackend = WindowsNativeAuthorityBackend & {
readonly identity: WindowsNativeAuthorityIdentity;
};
const require = createRequire(import.meta.url);
/** Production host backed by Node's exact CommonJS/native-addon loader. */
const systemWindowsNativeAuthorityLoadHost =
(): WindowsNativeAuthorityLoadHost => ({
platform: process.platform,
architecture: process.arch,
nodeApiVersion: parseNodeApiVersion(process.versions.napi),
resolve: (packageName) => require.resolve(packageName),
resolveManifest: (packageName) =>
require.resolve(`${packageName}/package.json`),
canonicalize: realpath,
read: readFile,
cached: (path) => require.cache[path]?.exports,
load: (path) => require(path),
});
/** Stateful process-lifetime loader for one pinned native module identity. */
export class WindowsNativeAuthorityPackageLoader {
private loaded: LoadedBackend | undefined;
private loading:
| Promise<
Result<WindowsNativeAuthorityBackend, WindowsNativeAuthorityError>
>
| undefined;
constructor(
private readonly host: WindowsNativeAuthorityLoadHost,
private readonly commitment: WindowsNativeAuthorityPackageCommitment,
) {}
/** Load once and pin either the backend or its failure for this process. */
load(): Promise<
Result<WindowsNativeAuthorityBackend, WindowsNativeAuthorityError>
> {
if (this.loaded !== undefined)
return Promise.resolve(ok(this.loaded.backend));
this.loading ??= this.loadOnce();
return this.loading;
}
private async loadOnce(): Promise<
Result<WindowsNativeAuthorityBackend, WindowsNativeAuthorityError>
> {
const supported = this.checkRuntime();
if (!supported.ok) return supported;
const manifest = await this.readManifest();
if (!manifest.ok) return manifest;
let resolvedPath: string;
try {
resolvedPath = await this.host.canonicalize(
this.host.resolve(this.commitment.packageName),
);
} catch (cause: unknown) {
return err(
loadError(
"unavailable",
"Windows native authority package is not installed or resolvable",
cause,
),
);
}
let expectedArtifactPath: string;
try {
expectedArtifactPath = await this.host.canonicalize(
win32.resolve(
win32.dirname(manifest.value.path),
manifest.value.artifact,
),
);
} catch (cause: unknown) {
return err(
loadError(
"unavailable",
"Windows native authority declared addon is unavailable",
cause,
),
);
}
if (resolvedPath !== expectedArtifactPath)
return err(
loadError(
"native_contract_mismatch",
"Windows native authority package resolved an unexpected addon path",
),
);
if (this.host.cached(resolvedPath) !== undefined)
return err(
loadError(
"native_contract_mismatch",
"Windows native authority addon was cached before identity verification",
),
);
let artifact: Uint8Array;
try {
artifact = await this.host.read(resolvedPath);
} catch (cause: unknown) {
return err(
loadError(
"unavailable",
"Windows native authority addon could not be read",
cause,
),
);
}
const digest = createHash("sha256").update(artifact).digest("hex");
if (digest !== this.commitment.artifactSha256)
return err(
loadError(
"identity_drift",
"Windows native authority addon digest does not match this REA release",
),
);
let module: unknown;
try {
module = this.host.load(resolvedPath);
} catch (cause: unknown) {
return err(
loadError(
"unavailable",
"Windows native authority addon could not be loaded",
cause,
),
);
}
const parsed = parseBackend(module, this.commitment, digest);
if (!parsed.ok) return parsed;
this.loaded = {
backend: parsed.value,
canonicalPath: resolvedPath,
identity: parsed.value.identity,
};
return ok(parsed.value);
}
private checkRuntime(): Result<void, WindowsNativeAuthorityError> {
if (this.host.platform !== "win32" || this.host.architecture !== "x64")
return err(
loadError(
"unavailable",
"Windows native authority requires Windows x64",
),
);
if (this.commitment.artifactSha256 === null)
return err(
loadError(
"unavailable",
"This REA build has no committed Windows native authority artifact",
),
);
if (
this.host.nodeApiVersion === null ||
this.host.nodeApiVersion < this.commitment.nodeApiVersion
)
return err(
loadError(
"unavailable",
"Windows native authority requires the committed Node-API version",
),
);
return ok(undefined);
}
private async readManifest(): Promise<
Result<
{ readonly path: string; readonly artifact: string },
WindowsNativeAuthorityError
>
> {
let path: string;
let bytes: Uint8Array;
try {
path = await this.host.canonicalize(
this.host.resolveManifest(this.commitment.packageName),
);
bytes = await this.host.read(path);
} catch (cause: unknown) {
return err(
loadError(
"unavailable",
"Windows native authority package manifest is unavailable",
cause,
),
);
}
let decoded: unknown;
try {
decoded = JSON.parse(Buffer.from(bytes).toString("utf8"));
} catch (cause: unknown) {
return err(
loadError(
"native_contract_mismatch",
"Windows native authority package manifest is not valid JSON",
cause,
),
);
}
const parsed = packageManifestSchema.safeParse(decoded);
if (
!parsed.success ||
parsed.data.name !== this.commitment.packageName ||
parsed.data.version !== this.commitment.packageVersion ||
parsed.data.reaNativeAuthority.contractVersion !==
this.commitment.contractVersion ||
parsed.data.reaNativeAuthority.nodeApiVersion !==
this.commitment.nodeApiVersion ||
parsed.data.reaNativeAuthority.artifactSha256 !==
this.commitment.artifactSha256
)
return err(
loadError(
"native_contract_mismatch",
"Windows native authority package manifest does not match this REA release",
),
);
return ok({
path,
artifact: parsed.data.reaNativeAuthority.artifact,
});
}
}
let productionLoader: WindowsNativeAuthorityPackageLoader | undefined;
/** Return the one process-global loader for release-generated package metadata. */
export const createWindowsNativeAuthorityPackageLoader =
(): WindowsNativeAuthorityPackageLoader => {
productionLoader ??= new WindowsNativeAuthorityPackageLoader(
systemWindowsNativeAuthorityLoadHost(),
PACKAGE_METADATA.windowsNativeAuthority,
);
return productionLoader;
};
const parseBackend = (
input: unknown,
commitment: WindowsNativeAuthorityPackageCommitment,
digest: string,
): Result<LoadedWindowsNativeBackend, WindowsNativeAuthorityError> => {
if (typeof input !== "object" || input === null)
return err(
loadError(
"native_contract_mismatch",
"Windows native authority addon exported a non-object contract",
),
);
const keys = Object.keys(input).sort((left, right) =>
left.localeCompare(right),
);
if (!sameStrings(keys, BACKEND_EXPORTS))
return err(
loadError(
"native_contract_mismatch",
"Windows native authority addon export set does not match the contract",
),
);
const candidate = input as Record<string, unknown>;
const identity = identitySchema.safeParse(candidate.identity);
if (!identity.success || !sameIdentity(identity.data, commitment, digest))
return err(
loadError(
"native_contract_mismatch",
"Windows native authority addon identity does not match this REA release",
),
);
if (
typeof candidate.admitFile !== "function" ||
typeof candidate.admitDirectory !== "function" ||
typeof candidate.createPrivateRoot !== "function" ||
typeof candidate.spawnOwnedProcess !== "function"
)
return err(
loadError(
"native_contract_mismatch",
"Windows native authority addon operations do not match the contract",
),
);
// SAFETY: the exact export set, identity, and every callable backend operation
// were checked above. Operation results remain parsed by WindowsNativeAuthority.
return ok(candidate as unknown as LoadedWindowsNativeBackend);
};
const sameIdentity = (
identity: WindowsNativeAuthorityIdentity,
commitment: WindowsNativeAuthorityPackageCommitment,
digest: string,
): boolean =>
identity.packageName === commitment.packageName &&
identity.packageVersion === commitment.packageVersion &&
identity.contractVersion === commitment.contractVersion &&
identity.nodeApiVersion === commitment.nodeApiVersion &&
identity.artifactSha256 === digest;
const sameStrings = (
actual: readonly string[],
expected: readonly string[],
): boolean =>
actual.length === expected.length &&
actual.every((value, index) => value === expected[index]);
const parseNodeApiVersion = (value: string | undefined): number | null => {
if (value === undefined || !/^\d+$/u.test(value)) return null;
const parsed = Number(value);
return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
};
const loadError = (
reason: "unavailable" | "identity_drift" | "native_contract_mismatch",
message: string,
cause?: unknown,
): WindowsNativeAuthorityError =>
new WindowsNativeAuthorityError(
"load_native_authority",
reason,
message,
cause === undefined ? undefined : { cause },
);