@schema-weaver/pg-connector 0.0.0-stage → 2.0.0

package/dist/esm/cli/doctor/checks.d.ts

@@ -0,0 +1,133 @@
+import { MachineConfig } from '../../config/machine-config';
+import { DatabasesConfig } from '../../config/db-config';
+export interface DoctorCheck {
+    name: string;
+    status: 'pass' | 'fail' | 'warn';
+    detail?: string;
+}
+export interface DoctorContext {
+    swAgentDir: string;
+    machineConfig: MachineConfig | null;
+    databasesConfig: DatabasesConfig | null;
+    nodeVersion: string;
+    platform: string;
+}
+export declare function checkSwAgentDirExists(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkMachineConfigValid(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkTokenFormat(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkDatabasesConfigValid(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkDatabasesReachable(ctx: DoctorContext): Promise<DoctorCheck>;
+/**
+ * Files whose contents are credential material and which must therefore be
+ * readable only by their owner.
+ */
+export declare const SECURE_CONFIG_FILES: readonly ["sw-agent.config.json", "databases.config.json"];
+/** Mode every config file must have: read/write for the owner, nothing else. */
+export declare const SECURE_CONFIG_MODE = 384;
+export interface ConfigFileMode {
+    name: string;
+    path: string;
+    mode: number | null;
+    /** True when the path exists but is not a regular file (symlink, socket, …). */
+    irregular: boolean;
+    exists: boolean;
+}
+/**
+ * Resolve the real config file paths and read their modes. Does not follow
+ * symlinks for the permission read: a symlinked config is reported as
+ * irregular rather than silently checking whatever it points at.
+ */
+export declare function inspectConfigFileModes(swAgentDir: string): ConfigFileMode[];
+export declare function formatMode(mode: number): string;
+/**
+ * Check that the config files are owner-only (0o600).
+ *
+ * `databases.config.json` holds encrypted database passwords and
+ * `sw-agent.config.json` holds the agent token that authenticates this agent to
+ * the cloud. A group- or world-readable copy of either is a credential
+ * disclosure to every other local user, so a 0o644 config FAILS here rather
+ * than producing a warning. Missing files are reported as a warning: their
+ * absence is covered by the config-validity checks.
+ */
+export declare function checkConfigFilePermissions(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkAuditDirWritable(ctx: DoctorContext): Promise<DoctorCheck>;
+/**
+ * Verifies the existing audit log against its anchor. A log that does not
+ * verify is reported as a failure, not a warning: an operator running `doctor`
+ * is exactly the person who needs to be told.
+ *
+ * This is the one caller that reuses {@link verifyAuditDirCached}: an operator
+ * running `doctor` repeatedly in the same shell re-verifies an unchanged log
+ * over and over, and the archives are the bulk of it. A reused file is only
+ * skipped when it is byte-identical to what was verified (dev/inode/size/mtime
+ * *and* ctime, at nanosecond precision), when the entry was verified from the
+ * chain state the walk is resuming into, when it was verified with the same
+ * signing key, and — for the end of the log — when the tail record on disk is
+ * still the record that was verified. The anchors are re-read from disk on
+ * every call. The result always says how much it did *not* read, so a pass
+ * backed by the cache can never look like a full re-read.
+ */
+export declare function checkAuditChain(ctx: DoctorContext): Promise<DoctorCheck>;
+/**
+ * Repairs an audit directory that exists with a mode that cannot be traversed.
+ * `mkdir({ recursive: true })` is a no-op on an existing directory, so without
+ * this the wrong mode is permanent and the audit log silently records nothing.
+ */
+export declare function ensureAuditDirForDoctor(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkDiskSpace(_ctx: DoctorContext): Promise<DoctorCheck>;
+/**
+ * One `rolX = false` expectation, parsed out of
+ * {@link RECOMMENDED_PG_ROLE}.required_attributes.
+ *
+ * The role policy is the single source of truth: the SQL and the expectations
+ * are both derived from it, so a new required attribute is enforced the moment
+ * it is documented rather than needing a second edit here.
+ */
+export interface PgRoleAttributeRule {
+    attribute: string;
+    expect: boolean;
+}
+/**
+ * What the connected login role actually holds, as read from the server. Every
+ * probe is nullable: an unanswered probe must never read as "acceptable".
+ */
+export interface PgRoleFacts {
+    alias: string;
+    role: string;
+    /** `pg_roles` attribute name -> value, or null when the probe did not answer. */
+    attributes: Record<string, boolean | null>;
+    can_create_temp: boolean | null;
+    can_create_in_public: boolean | null;
+    /** Predefined roles the login role holds, directly or by inheritance. */
+    forbidden_memberships: string[];
+    default_transaction_read_only: string | null;
+}
+/**
+ * Every way the connected role departs from {@link RECOMMENDED_PG_ROLE}, as
+ * human-readable findings. An empty array means the role is acceptable.
+ *
+ * Pure and fail-closed: an unanswered probe is itself a finding, because a probe
+ * that did not answer has not established anything.
+ */
+export declare function pgRoleFindings(facts: PgRoleFacts): string[];
+/** The label the role check reports under. */
+export declare const PG_ROLE_CHECK_NAME: string;
+/**
+ * Verifies the connected PostgreSQL login role against
+ * {@link RECOMMENDED_PG_ROLE} (C-02).
+ *
+ * `read_only` constrains what the connector is willing to run; it cannot
+ * constrain what the login role is allowed to do. A `rolsuper` or
+ * `pg_read_server_files` role defeats every control above it, so the role is
+ * the only boundary an operator cannot route around from the wire.
+ *
+ * A violation is a failure, not a warning: the operator running `doctor` is
+ * exactly the person who needs to be told. A database that cannot be reached
+ * cannot clear the role, so it is reported as a warning naming what was not
+ * checked — never as a pass.
+ */
+export declare function checkPgRoleLeastPrivilege(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkNodeVersion(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkPidFile(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function runAllChecks(ctx: DoctorContext): Promise<DoctorCheck[]>;
+//# sourceMappingURL=checks.d.ts.map

package/dist/esm/cli/doctor/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../../../../src/cli/doctor/checks.ts"],"names":[],"mappings":"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"}