ardent-cli-beta 0.0.20 → 0.1.0

package/README.md

@@ -39,6 +39,12 @@ omitting it preserves unrestricted ingress. `--print` remains accepted. The cred
 after exit. This uses `branch connect --print`'s lifecycle and requires a control
 plane that issues credentials while branches start (`docs/DECISIONS.md` section 17).
 
+For tokenized credentials, the CLI receives the database token once, keeps it
+in memory while waiting for readiness, and composes the delivered URL template
+locally. A lost one-time token requires revoking and issuing another credential;
+recovery records contain only request and issuance metadata, never that token
+(`docs/DECISIONS.md` section 20).
+
 Use `branch create <name> --to-env` or `branch connect --to-env` to write
 `DATABASE_URL` to `.env` in the
 current directory instead of printing the URL. The selected `--driver` still
@@ -133,7 +139,9 @@ context and names the status command before retrying.
 Creation uses the connector's latest published snapshot. If that snapshot is
 unavailable, creation fails without choosing an older one. Names are unique within
 a connector while the branch is not deleted. `branch delete` sends the connector
-and name to the API, which resolves the target. `branch list` fetches current state
+and name to the API, which resolves the target. When no branch has that name and
+the argument is the ID of a deleted branch whose erasure is unconfirmed, as a
+refused `connector delete` names one, it retries that erasure. `branch list` fetches current state
 and marks the locally selected branch with `●` in its `Selected` column; `branch switch` changes local
 context. Create and delete follow the operation in an interactive terminal;
 creation also waits outside a terminal and with `--json` so it can return a usable

package/dist/branches/client.d.ts

@@ -15,6 +15,9 @@ export interface BranchOperation {
 export declare function listBranches(token: string, connectorID: string): Promise<Branch[]>;
 export declare function createBranch(token: string, connectorID: string, name: string, allowedCIDRs?: string[]): Promise<BranchOperation>;
 export declare function deleteBranch(token: string, connectorID: string, name: string): Promise<BranchOperation>;
+export declare function isBranchID(value: string): boolean;
+export declare function loadDeletedBranch(token: string, connectorID: string, id: string): Promise<Branch>;
+export declare function retryBranchErasure(token: string, branch: Branch): Promise<BranchOperation>;
 export type BranchLifecycleAction = 'wake' | 'suspend' | 'recover';
 export declare function transitionBranch(token: string, connectorID: string, name: string, action: BranchLifecycleAction): Promise<BranchOperation>;
 export declare function waitForBranchOperation(token: string, workflowID: string, onStatus?: (status: string) => void, failedReads?: 'stop' | 'retry'): Promise<void>;

package/dist/branches/client.js

@@ -23,6 +23,50 @@ export async function deleteBranch(token, connectorID, name) {
     validateOperation(result, connectorID, name);
     return result;
 }
+// A deleted branch whose erasure no node has confirmed is in no branch list
+// and unreachable by name, yet keeps its connector from being deleted; that
+// refusal names it by ID. These two calls resolve such an ID and retry its
+// erasure by ID. docs/DECISIONS.md section 19 says why only a DELETED branch.
+export function isBranchID(value) {
+    return /^branch_[0-9A-Za-z_-]+$/.test(value);
+}
+export async function loadDeletedBranch(token, connectorID, id) {
+    const missing = `No branch ${terminalText(id)} in the selected connector.`;
+    let branch;
+    try {
+        branch = await request(token, `/branches/${encodeURIComponent(id)}`);
+    }
+    catch (error) {
+        if (error instanceof APIError && error.status === 404)
+            throw new Error(missing, { cause: error });
+        throw error;
+    }
+    if (!isBranch(branch, connectorID) || branch.id !== id)
+        throw new Error(missing);
+    if (branch.state !== 'DELETED')
+        throw new Error(`Branch ${terminalText(id)} is not deleted. Delete it by its name, ${terminalText(JSON.stringify(branch.name))}.`);
+    return branch;
+}
+export async function retryBranchErasure(token, branch) {
+    let operation;
+    try {
+        // branch list omits a deleted branch and no CLI command reads one, so the
+        // refresh is the read loadDeletedBranch made.
+        operation = await requestDurableMutation(token, `/branches/${encodeURIComponent(branch.id)}`, { method: 'DELETE' }, `an authenticated GET /branches/${terminalText(encodeURIComponent(branch.id))}`);
+    }
+    catch (error) {
+        // This route refuses in plain text, so the API's reason does not reach here.
+        if (error instanceof APIError && error.status === 409) {
+            throw new Error(`The Ardent API refused to retry the erasure of branch ${terminalText(branch.id)}. An erasure still running can be retried once it fails, an hour after it was requested; otherwise report the branch ID to Ardent support.`, { cause: error });
+        }
+        throw error;
+    }
+    if (!operation || typeof operation.operation_id !== 'string' || !operation.operation_id ||
+        typeof operation.workflow_id !== 'string' || !operation.workflow_id) {
+        throw new Error(`The Ardent API accepted the erasure retry of branch ${terminalText(branch.id)} but returned no valid operation; completion is unknown and work may still be running.`);
+    }
+    return { branch, operation };
+}
 // The control plane addresses these transitions by branch ID, so the command
 // resolves the name in the selected connector first and acts on exactly that
 // branch. The response is the operation alone; the resolved branch is returned

package/dist/branches/connection.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { acknowledgeBranchCredential, CredentialIssueRefused, issueBranchCredential, revokeBranchCredential, waitForBranchCredential } from './credentials.js';
+import { acknowledgeBranchCredential, composeCredentialDelivery, CredentialIssueRefused, issuedConnectKey, issueBranchCredential, revokeBranchCredential, waitForBranchCredential } from './credentials.js';
 import { CLIENT_REQUIREMENTS, connectionString } from './drivers.js';
 import { connectionEnvironment, runPsql } from './psql.js';
 import { CredentialRecoveryCleanupError, forgetCredentialRecovery, openCredentialWitness, rememberCredentialIssuance, rememberCredentialRequest } from './recovery.js';
@@ -15,6 +15,7 @@ export async function connectToBranch(connection) {
     try {
         const recovery = await rememberCredentialRequest(connection.configDir, branchID, token, witness.port, requestID, sourceRole);
         let issuanceID;
+        let connectKey;
         let issueRefused = false;
         // Set once a printed credential's recovery record is gone: the
         // credential is the user's from then on, and nothing here revokes it.
@@ -25,7 +26,10 @@ export async function connectToBranch(connection) {
         let failure;
         try {
             try {
-                issuanceID = await issueBranchCredential(token, branchID, requestID, sourceRole);
+                const issued = await issueBranchCredential(token, branchID, requestID, sourceRole);
+                issuanceID = issued.issuanceID;
+                await rememberCredentialIssuance(recovery, issuanceID);
+                connectKey = issuedConnectKey(issued);
             }
             catch (error) {
                 if (error instanceof CredentialIssueRefused) {
@@ -42,8 +46,7 @@ export async function connectToBranch(connection) {
                 }
                 throw error;
             }
-            await rememberCredentialIssuance(recovery, issuanceID);
-            const delivery = await deliverWhenServing(token, issuanceID, connection.serving);
+            const delivery = composeCredentialDelivery(await deliverWhenServing(token, issuanceID, connection.serving), connectKey);
             if (print) {
                 // Checked before acknowledgement, so a form that would not verify
                 // the server is revoked, never handed over.

package/dist/branches/credentials.d.ts

@@ -1,9 +1,15 @@
 import { type ConnectionStrings } from './drivers.js';
+export interface IssuedCredential {
+    issuanceID: string;
+    connectKey?: unknown;
+    connectKeyRequired?: unknown;
+}
 interface DeliveredCredential {
     issuance_id: string;
     delivery_id: string;
     uri: string;
     connection_strings?: ConnectionStrings;
+    connect_key_required?: boolean;
 }
 export declare class CredentialIssueRefused extends Error {
     readonly code?: string | undefined;
@@ -11,7 +17,9 @@ export declare class CredentialIssueRefused extends Error {
 }
 export declare function validSourceRole(role: string): boolean;
 export declare function refusedBeforeIssuance(error: unknown): boolean;
-export declare function issueBranchCredential(token: string, branchID: string, requestID: string, sourceRole?: string): Promise<string>;
+export declare function issueBranchCredential(token: string, branchID: string, requestID: string, sourceRole?: string): Promise<IssuedCredential>;
+export declare function issuedConnectKey(issued: IssuedCredential): string | undefined;
+export declare function composeCredentialDelivery(delivered: DeliveredCredential, connectKey?: string): DeliveredCredential;
 export declare function waitForBranchCredential(token: string, issuanceID: string, stop?: AbortSignal, served?: Promise<void>): Promise<DeliveredCredential>;
 export declare function acknowledgeBranchCredential(token: string, issuanceID: string, deliveryID: string): Promise<void>;
 export declare function revokeBranchCredential(token: string, issuanceID: string): Promise<void>;

package/dist/branches/credentials.js

@@ -11,7 +11,7 @@ export class CredentialIssueRefused extends Error {
 }
 // The issuance refusals that come before any issuance is recorded: a request
 // refused with one of these left nothing to revoke.
-const sourceRoleIssueRefusals = new Set(['invalid_source_role', 'source_role_unsupported', 'source_role_held', 'source_role_revocation_pending']);
+const sourceRoleIssueRefusals = new Set(['invalid_source_role', 'source_role_unsupported', 'source_role_held', 'source_role_revocation_pending', 'connect_key_unsupported']);
 // sourceRolePattern is the name the API accepts for a source role: an
 // unquoted lower-case PostgreSQL identifier that begins with neither pg_ nor
 // ardent. The CLI checks it before it records or sends anything, so a mistyped
@@ -53,7 +53,58 @@ export async function issueBranchCredential(token, branchID, requestID, sourceRo
     if (!result || typeof result.issuance_id !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(result.issuance_id) || result.status !== 'pending') {
         throw new Error('Ardent API returned an invalid branch credential issuance.');
     }
-    return result.issuance_id;
+    // Return the identity before checking the one-time secret, so the caller
+    // records and revokes an issuance even when its secret is absent or malformed.
+    return { issuanceID: result.issuance_id, connectKey: result.connect_key, connectKeyRequired: result.connect_key_required };
+}
+export function issuedConnectKey(issued) {
+    if (issued.connectKeyRequired === undefined || issued.connectKeyRequired === false) {
+        if (issued.connectKey !== undefined)
+            throw new Error('Ardent API returned an unexpected database token. Revoke this credential and issue another.');
+        return undefined;
+    }
+    if (issued.connectKeyRequired !== true || typeof issued.connectKey !== 'string' ||
+        !/^bck_[a-z2-7]{16}_[A-Za-z0-9_-]{43}$/.test(issued.connectKey) ||
+        Buffer.from(issued.connectKey.slice(21), 'base64url').toString('base64url') !== issued.connectKey.slice(21)) {
+        throw new Error('The one-time database token was not received. Revoke this credential and issue another; the token cannot be recovered.');
+    }
+    return issued.connectKey;
+}
+// Tokenized delivery contains templates, never a recoverable database token.
+// Compose only the username field locally; neither password nor query settings
+// are interpolated. The ordinary driver checks still validate TLS afterwards.
+export function composeCredentialDelivery(delivered, connectKey) {
+    if (delivered.connect_key_required !== undefined && typeof delivered.connect_key_required !== 'boolean') {
+        throw new Error('Ardent API returned an invalid database token requirement.');
+    }
+    if (Boolean(connectKey) !== (delivered.connect_key_required === true)) {
+        throw new Error('Ardent API returned an inconsistent database token requirement.');
+    }
+    if (!connectKey)
+        return delivered;
+    const compose = (value, jdbc = false) => {
+        try {
+            if (jdbc && !value.startsWith('jdbc:postgresql://'))
+                throw new Error();
+            const url = new URL(jdbc ? value.slice('jdbc:'.length) : value);
+            const user = jdbc ? url.searchParams.get('user') : decodeURIComponent(url.username);
+            if (!user || !/^[a-z_][a-z0-9_]{0,62}\+<connect-key>$/.test(user) || (jdbc && url.searchParams.getAll('user').length !== 1))
+                throw new Error();
+            const username = `${user.slice(0, -'<connect-key>'.length)}${connectKey}`;
+            if (jdbc)
+                url.searchParams.set('user', username);
+            else
+                url.username = username;
+            return `${jdbc ? 'jdbc:' : ''}${url.toString()}`;
+        }
+        catch {
+            throw new Error('Ardent API returned an invalid database token template.');
+        }
+    };
+    const uri = compose(delivered.uri);
+    const strings = delivered.connection_strings;
+    const connectionStrings = strings && Object.fromEntries(DRIVERS.map((driver) => [driver, compose(strings[driver], driver === 'jdbc')]));
+    return { ...delivered, uri, connection_strings: connectionStrings };
 }
 // stop, when given, ends the wait with its abort reason: a caller that learns
 // the branch failed has no delivery left to wait for. served, when given,

package/dist/branches/psql.js

@@ -26,7 +26,8 @@ export function connectionEnvironment(uri) {
     }
     const parameters = [...url.searchParams.entries()];
     const controls = /[\u0000-\u001f\u007f]/;
-    // A terminating environment's username is <role>+<api key>, which its node
+    // A terminating environment's username is <role>+<database token> (or a
+    // legacy API key), which its node
     // proxy splits; a passthrough environment's is the role alone, because no
     // proxy is there to split it. Either way neither half may be empty.
     const [role, ...apiKey] = user.split('+');
@@ -80,7 +81,7 @@ export async function checkPsql() {
     });
 }
 export async function runPsql(connection) {
-    // The API key is embedded in PGUSER. Neither the URI nor PGUSER reaches argv.
+    // The database token or legacy API key is in PGUSER. Neither it nor the URI reaches argv.
     const environment = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('PG')));
     await new Promise((resolve, reject) => {
         const child = spawn('script', terminalCommand(['-X', '-v', 'PROMPT1=ardent=> ', '-v', 'PROMPT2=ardent-> ', '-v', 'PROMPT3=ardent>> ']), {

package/dist/branches/recovery.js

@@ -185,7 +185,7 @@ export async function recoverBranchCredentials(directory, token) {
             if (!recovery.issuanceID) {
                 let issuanceID;
                 try {
-                    issuanceID = await issueBranchCredential(token, branchID, requestID, recovery.sourceRole);
+                    issuanceID = (await issueBranchCredential(token, branchID, requestID, recovery.sourceRole)).issuanceID;
                 }
                 catch (error) {
                     // The API refuses a source role before it records an issuance and

package/dist/commands/branch/delete.js

@@ -1,11 +1,12 @@
 import { Args, ux } from '@oclif/core';
+import { APIError } from '../../api/client.js';
 import { ArdentCommand } from '../../command.js';
-import { branchName, deleteBranch, waitForBranchOperation } from '../../branches/client.js';
+import { branchName, deleteBranch, isBranchID, loadDeletedBranch, retryBranchErasure, waitForBranchOperation } from '../../branches/client.js';
 import { replaceBranchCache } from '../../branches/context.js';
 import { requireConnector } from '../../connectors/context.js';
 import { terminalText } from '../../terminal.js';
 export default class BranchDelete extends ArdentCommand {
-    static args = { name: Args.string({ description: 'Branch name', required: true }) };
+    static args = { name: Args.string({ description: 'Branch name, or the ID of a deleted branch whose erasure to retry', required: true }) };
     static strict = false;
     static description = 'Delete a branch in the selected connector';
     static helpGroup = 'Branches';
@@ -20,7 +21,25 @@ export default class BranchDelete extends ArdentCommand {
         else if (!this.jsonEnabled())
             this.log(`Deleting branch ${target}...`);
         try {
-            const result = await deleteBranch(session.token, session.selectedConnector.id, name);
+            let result;
+            try {
+                result = await deleteBranch(session.token, session.selectedConnector.id, name);
+            }
+            catch (error) {
+                // A name that matches no branch may be the ID of a deleted branch
+                // whose erasure is unconfirmed (retryBranchErasure).
+                if (!(error instanceof APIError && error.status === 404 && error.code === 'branch_not_found' && isBranchID(name)))
+                    throw error;
+                const branch = await loadDeletedBranch(session.token, session.selectedConnector.id, name);
+                const retry = `Retrying the erasure of deleted branch ${terminalText(branch.name)} (${terminalText(branch.id)}) in connector ${terminalText(session.selectedConnector.name)}`;
+                if (interactive) {
+                    ux.action.stop('no branch has that name');
+                    ux.action.start(retry);
+                }
+                else if (!this.jsonEnabled())
+                    this.log(`${retry}...`);
+                result = await retryBranchErasure(session.token, branch);
+            }
             if (interactive) {
                 await waitForBranchOperation(session.token, result.operation.workflow_id, (status) => { ux.action.status = status; });
                 await replaceBranchCache(this.config.configDir, session, (session.branches ?? []).filter(({ id }) => id !== result.branch.id));

package/oclif.manifest.json

@@ -239,7 +239,7 @@
       "aliases": [],
       "args": {
         "name": {
-          "description": "Branch name",
+          "description": "Branch name, or the ID of a deleted branch whose erasure to retry",
           "name": "name",
           "required": true
         }
@@ -908,5 +908,5 @@
       ]
     }
   },
-  "version": "0.0.20"
+  "version": "0.1.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ardent-cli-beta",
-  "version": "0.0.20",
+  "version": "0.1.0",
   "description": "The Ardent command-line interface",
   "license": "Apache-2.0",
   "type": "module",