@elinpf/dsh-ops-access 0.2.1 → 0.4.0

package/lib/backend.d.ts

@@ -18,6 +18,8 @@
  */
 import type { EntryEnvelope, ProbeState } from './types.js';
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Expand a leading `~` (or `~/`) to the user's home directory. */
+export declare function expandHome(p: string): string;
 /** Build an EntryEnvelope from raw entry data, taking each envelope field from the first source that has it. */
 export declare function buildEnvelope(sources: Array<Record<string, unknown> | undefined>): EntryEnvelope;
 /** Read a persisted probe result off a raw tier object (durable boundary — sanitize). */

package/lib/backend.js

@@ -17,11 +17,21 @@
  * @module @elinpf/dsh-ops-access/backend
  */
 import { readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 // ── Shared helpers ───────────────────────────────────────────────────────────
 export function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/** Expand a leading `~` (or `~/`) to the user's home directory. */
+export function expandHome(p) {
+    const home = process.env.HOME ?? os.homedir();
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/'))
+        return home + p.slice(1);
+    return p;
+}
 /** Build an EntryEnvelope from raw entry data, taking each envelope field from the first source that has it. */
 export function buildEnvelope(sources) {
     const envelope = {};

package/lib/hub-backend.d.ts

@@ -75,7 +75,7 @@ export declare class HubBackend implements AccessBackend {
         reason?: string;
     }): Promise<string>;
     /** Pending-request metadata for the approval UI — field values never cross. */
-    listRequests(status?: 'pending' | 'approved' | 'rejected'): Promise<unknown>;
+    listRequests(): Promise<unknown>;
     /** Full request incl. field values, for pre-approval review. Null when absent. */
     getRequest(id: string): Promise<unknown>;
     /** Approve (hub writes the tier) or reject. Returns false when already settled/absent. */

package/lib/hub-backend.js

@@ -23,17 +23,7 @@
  */
 import { mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
-import os from 'node:os';
-import { buildEnvelope, isPlainObject, mergeEnvelope, probeOf } from './backend.js';
-/** Expand a leading `~` (or `~/`) to the user's home directory. */
-function expandHome(p) {
-    const home = process.env.HOME ?? os.homedir();
-    if (p === '~')
-        return home;
-    if (p.startsWith('~/'))
-        return home + p.slice(1);
-    return p;
-}
+import { buildEnvelope, expandHome, isPlainObject, mergeEnvelope, probeOf } from './backend.js';
 /**
  * Write content to a managed file, skipping the write when the on-disk
  * bytes already match (resolve runs on every tool call — touching the file
@@ -253,8 +243,8 @@ export class HubBackend {
         return data.id;
     }
     /** Pending-request metadata for the approval UI — field values never cross. */
-    async listRequests(status) {
-        return this.request('GET', status === undefined ? '/requests' : `/requests?status=${status}`);
+    async listRequests() {
+        return this.request('GET', '/requests?status=pending');
     }
     /** Full request incl. field values, for pre-approval review. Null when absent. */
     async getRequest(id) {

package/lib/index.d.ts

@@ -55,9 +55,12 @@ export interface Config {
      * Credential source: 'yaml' (default) reads the local registry file;
      * 'hub' fetches entries from a remote ops-access-hub service on every
      * call and materializes file-field content to managed local files.
+     * Unset + env ACCESS_HUB_URL present → 'hub' (upgrade-proof seam: the
+     * materialized preset file is rewritten on every suite upgrade, so the
+     * durable switch lives in the process environment, e.g. the systemd unit).
      */
     source?: 'yaml' | 'hub';
-    /** Hub base URL (source: 'hub'), e.g. http://127.0.0.1:3090. */
+    /** Hub base URL (source: 'hub'), e.g. http://127.0.0.1:3090. Falls back to env ACCESS_HUB_URL. */
     hubUrl?: string;
     /** Hub read token (source: 'hub'); falls back to env ACCESS_HUB_READ_TOKEN. Never logged. */
     hubToken?: string;
@@ -80,7 +83,7 @@ export interface Config {
     hubCacheDir?: string;
 }
 export declare const Config: z<Config>;
-export type { AccessProvider, AccessProfile, EntryEnvelope, ProbeState, AdminTierStatus, AdminEntry, KindDescriptor, AccessAgent, AccessBrokerDecision, AccessBroker, OpsAccess, } from './types.js';
+export type { AccessProvider, AccessProfile, EntryEnvelope, ProbeState, AdminTierStatus, AdminEntry, KindDescriptor, AccessAgent, AccessBrokerDecision, AccessBroker, AccessRequest, OpsAccess, } from './types.js';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         opsAccess?: OpsAccess;
@@ -102,6 +105,13 @@ export declare function registerAccessProvider(ctx: Context, provider: AccessPro
  * `ctx.inject` and ties the registration to the plugin's effect lifecycle.
  */
 export declare function registerAccessBroker(ctx: Context, broker: AccessBroker): void;
-/** Expand a leading `~` (or `~/`) to the user's home directory. */
-export declare function expandHome(p: string): string;
+import { expandHome } from './backend.js';
+export { expandHome };
+/**
+ * Single-line-secret check shared by provider validateContent hooks: a
+ * pasted value may carry one trailing newline; anything further (interior
+ * `\n`/`\r`) means a multi-line paste landed in a field whose reader only
+ * honors the first line (sshpass -f, an Authorization header).
+ */
+export declare function hasSingleLineBody(content: string): boolean;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -57,8 +57,10 @@ export const inject = ['tools'];
 export const Config = z.object({
     registryFile: z.string().default('~/.dsh-ops/access.yaml'),
     credentialsDir: z.string().default('~/.dsh-ops/credentials'),
-    source: z.union(['yaml', 'hub']).default('yaml'),
-    hubUrl: z.string().default(''),
+    // No defaults here: an absent key must STAY absent so apply() can tell
+    // "unset" apart from an explicit value (the ACCESS_HUB_URL env seam).
+    source: z.union(['yaml', 'hub']),
+    hubUrl: z.string(),
     hubToken: z.string().default(''),
     hubAdminToken: z.string().default(''),
     materializeTtlMinutes: z.number().default(15),
@@ -90,14 +92,17 @@ export function registerAccessBroker(ctx, broker) {
     });
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
-/** Expand a leading `~` (or `~/`) to the user's home directory. */
-export function expandHome(p) {
-    const home = process.env.HOME ?? os.homedir();
-    if (p === '~')
-        return home;
-    if (p.startsWith('~/'))
-        return home + p.slice(1);
-    return p;
+import { expandHome } from './backend.js';
+export { expandHome };
+/**
+ * Single-line-secret check shared by provider validateContent hooks: a
+ * pasted value may carry one trailing newline; anything further (interior
+ * `\n`/`\r`) means a multi-line paste landed in a field whose reader only
+ * honors the first line (sshpass -f, an Authorization header).
+ */
+export function hasSingleLineBody(content) {
+    const body = content.endsWith('\n') ? content.slice(0, -1) : content;
+    return !body.includes('\n') && !body.includes('\r');
 }
 /**
  * Validate one tier sub-object against the provider schema and build the
@@ -381,7 +386,11 @@ export function apply(ctx, config) {
     // default and behaves byte-for-byte as before; hub fetches entries from a
     // remote ops-access-hub on every call and materializes file-field content
     // to managed local files under credentialsDir.
-    const source = config.source ?? 'yaml';
+    // Env seam (ACCESS_HUB_URL): setting it flips an unconfigured deployment to
+    // hub mode. The ops preset file is re-materialized on every suite upgrade,
+    // so config written into it is silently dropped — the process env (systemd
+    // unit) is the only upgrade-proof seam.
+    const source = config.source ?? (process.env.ACCESS_HUB_URL ? 'hub' : 'yaml');
     // In hub mode every local credential file — materialized reads AND staged
     // writes — lives under hubCacheDir as a TTL-bound cache. credentialsDir
     // stays yaml-mode territory: the sweeper must never touch files the yaml
@@ -389,9 +398,9 @@ export function apply(ctx, config) {
     const contentDir = source === 'hub' ? expandHome(config.hubCacheDir ?? '~/.dsh-ops/hub-cache') : credentialsDir;
     let backend;
     if (source === 'hub') {
-        const hubUrl = (config.hubUrl ?? '').replace(/\/+$/, '');
+        const hubUrl = (config.hubUrl || process.env.ACCESS_HUB_URL || '').replace(/\/+$/, '');
         if (hubUrl === '') {
-            throw new Error('ops-access: source "hub" requires hubUrl (e.g. http://127.0.0.1:3090)');
+            throw new Error('ops-access: source "hub" requires hubUrl (e.g. http://127.0.0.1:3090) or env ACCESS_HUB_URL');
         }
         backend = new HubBackend({
             baseUrl: hubUrl,
@@ -491,7 +500,7 @@ export function apply(ctx, config) {
                 return { ok: false, error: String(err?.message ?? err) };
             }
         },
-        async resolve(kind, profileName, agent) {
+        async resolve(kind, profileName, agent, request) {
             profileName = stripKindPrefix(kind, profileName);
             const provider = providers.get(kind);
             if (!provider) {
@@ -501,15 +510,21 @@ export function apply(ctx, config) {
             // Once a broker is registered it is consulted on EVERY resolve —
             // including calls without an agent. The no-agent ruling (fail closed to
             // ro, or deny outright) is policy, and policy lives in the broker, not
-            // here. Without a broker, rw is never issued at all.
+            // here. Without a broker, rw is never issued at all — so an explicit rw
+            // request without a broker is an error, not a silent ro.
             let tier = 'ro';
             if (broker) {
-                const decision = broker(kind, profileName, agent);
+                const decision = broker(kind, profileName, agent, request);
                 if (typeof decision === 'object') {
                     throw new Error(`ops-access: access denied for ${kind}/${profileName}: ${decision.deny}`);
                 }
-                if (decision === 'rw')
-                    tier = 'rw';
+                // An explicit 'ro' request caps the outcome at ro even when the broker
+                // would issue rw — the deliberate downgrade is the point: the caller
+                // declares "this call only reads".
+                tier = request?.tier === 'ro' ? 'ro' : decision;
+            }
+            else if (request?.tier === 'rw') {
+                throw new Error(`ops-access: rw tier requested for ${kind}/${profileName}, but no access gate is mounted — rw is never issued without one`);
             }
             // A missing SOURCE (yaml: no registry file) throws from the backend
             // verbatim (SourceUnavailableError); an unreadable source propagates
@@ -1041,7 +1056,7 @@ export function apply(ctx, config) {
                             sendJsonError(res, 405, new Error('method not allowed'));
                             return;
                         }
-                        const list = await backend.listRequests('pending');
+                        const list = await backend.listRequests();
                         res.writeHead(200, { 'content-type': 'application/json' });
                         res.end(JSON.stringify(list));
                     }

package/lib/types.d.ts

@@ -204,15 +204,28 @@ export interface AccessAgent {
 export type AccessBrokerDecision = 'ro' | 'rw' | {
     deny: string;
 };
+/**
+ * What the caller asked for on one resolve call, beyond the defaults.
+ */
+export interface AccessRequest {
+    /**
+     * Explicit tier declaration. `'ro'` is a deliberate downgrade: the session
+     * may hold an rw grant, but this call only reads — the ro credential is
+     * served (a lockdown deny still applies). `'rw'` is an explicit elevation
+     * request: the broker must deny loudly (with guidance) when the session
+     * holds no grant, rather than silently serving ro.
+     */
+    tier?: 'ro' | 'rw';
+}
 /**
  * The pure decision function a gate registers. Receives only kind, profile
- * name, and the caller agent — never credential fields. Once a broker is
- * registered, resolve consults it on EVERY call; `agent` is `undefined` for
- * system-internal calls, and the no-agent ruling belongs to the broker (core
- * does not answer policy on its behalf). Without a registered broker, resolve
- * is unchanged from the broker-less behavior (ro).
+ * name, the caller agent, and the per-call request — never credential fields.
+ * Once a broker is registered, resolve consults it on EVERY call; `agent` is
+ * `undefined` for system-internal calls, and the no-agent ruling belongs to
+ * the broker (core does not answer policy on its behalf). Without a
+ * registered broker, resolve is unchanged from the broker-less behavior (ro).
  */
-export type AccessBroker = (kind: string, name: string, agent: AccessAgent | undefined) => AccessBrokerDecision;
+export type AccessBroker = (kind: string, name: string, agent: AccessAgent | undefined, request?: AccessRequest) => AccessBrokerDecision;
 /** The ops access handle exposed via ctx.get('opsAccess'). */
 export interface OpsAccess {
     /** Register a credential-kind provider. Throws if the kind is already registered. Returns a disposer. */
@@ -245,7 +258,18 @@ export interface OpsAccess {
      * a broker the ro profile (from `registryFile`) is served, byte-for-byte
      * as before.
      */
-    resolve(kind: string, name: string, agent?: AccessAgent): Promise<AccessProfile>;
+    /**
+     * Resolve one profile by kind and name. Throws on unknown kind, unknown
+     * name, or invalid entry. When a broker is registered it is consulted on
+     * every call — including calls without an `agent` (the broker owns the
+     * no-agent ruling) — and decides whether the rw profile is served. Without
+     * a broker the ro profile (from `registryFile`) is served, byte-for-byte
+     * as before. `request.tier` lets the caller declare the tier explicitly:
+     * `'ro'` caps the outcome at ro even under an rw grant (deliberate
+     * downgrade); `'rw'` demands the rw tier and fails loudly when it cannot
+     * be served.
+     */
+    resolve(kind: string, name: string, agent?: AccessAgent, request?: AccessRequest): Promise<AccessProfile>;
     /** List all profiles across all registered kinds. Sections without a registered provider are skipped. */
     list(): Promise<AccessProfile[]>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elinpf/dsh-ops-access",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Ops access capability seam — owns the YAML credential registry and exposes ctx.opsAccess (resolve/list/register) to provider plugins.",
   "type": "module",
   "main": "lib/index.js",