open-source/qinglong
1
0
Fork 0
mirror of https://github.com/whyour/qinglong.git synced 2026-09-23 12:05:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(ql3): gate local secret transitions before activation

Browse Source
This commit is contained in:
whyour
2026-08-13 20:29:47 +08:00
parent 326783ff14
commit c877147d0f
37 changed files with 2495 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/ql3-local-owner-cli/src/plugin-package/pluginPackageCommand.ts
+123 -2
View File
@@ -30,6 +30,10 @@ import {
normalizePluginPackageSecretBindingPlan,
type PluginPackageSecretBindingPlan,
} from '@qinglong/runtime-core/plugin-package-secret-binding-plan';
import {
normalizePluginPackageSecretBindingTransitionPlan,
type PluginPackageSecretBindingTransitionPlan,
} from '@qinglong/runtime-core/plugin-package-secret-binding-transition-plan';
import {
pluginPackageInstallRecoveryAction,
type PluginPackageInstallActionInput,
@@ -206,6 +210,30 @@ export interface ExecuteLocalPluginPackageSecretBindingCommand {
};
}
export interface PlanLocalPluginPackageSecretBindingTransitionCommand {
readonly schemaVersion: 1;
readonly operation: 'plugin-package.secret-binding.transition.plan';
readonly options: LocalPluginPackageCommandOptions;
readonly request: {
readonly projectId: string;
readonly packageName: string;
readonly assignments: readonly Readonly<{
name: string;
secretRef: string | null;
}>[];
};
}
export interface ExecuteLocalPluginPackageSecretBindingTransitionCommand {
readonly schemaVersion: 1;
readonly operation: 'plugin-package.secret-binding.transition.execute';
readonly options: LocalPluginPackageCommandOptions;
readonly request: {
readonly plan: PluginPackageSecretBindingTransitionPlan;
readonly auditEventId: string;
};
}
export type LocalPluginPackageCommand =
| ProposeLocalPluginPackageCommand
| DecideLocalPluginPackageCommand
@@ -217,7 +245,9 @@ export type LocalPluginPackageCommand =
| PlanLocalPluginPackageLifecycleCommand
| ExecuteLocalPluginPackageLifecycleCommand
| PlanLocalPluginPackageSecretBindingCommand
| ExecuteLocalPluginPackageSecretBindingCommand;
| ExecuteLocalPluginPackageSecretBindingCommand
| PlanLocalPluginPackageSecretBindingTransitionCommand
| ExecuteLocalPluginPackageSecretBindingTransitionCommand;
export interface LocalPluginPackageCommandRunner {
run(
@@ -295,6 +325,21 @@ export type LocalPluginPackageCommandResult =
status: 'created' | 'existing';
bindingDigest: string;
generationDigest: string;
}>
| Readonly<{
schemaVersion: 1;
operation: 'plugin-package.secret-binding.transition.plan';
plan: Readonly<PluginPackageSecretBindingTransitionPlan>;
summary: ReturnType<typeof secretBindingTransitionPlanSummary>;
}>
| Readonly<{
schemaVersion: 1;
operation: 'plugin-package.secret-binding.transition.execute';
status: 'created' | 'existing';
transitionDigest: string;
receiptDigest: string;
bindingDigest: string | null;
generationDigest: string;
}>;
export class LocalPluginPackageCommandConfigurationError extends TypeError {
@@ -603,6 +648,7 @@ function normalizeCommand(value: unknown): Readonly<LocalPluginPackageCommand> {
}
break;
case 'plugin-package.secret-binding.plan':
case 'plugin-package.secret-binding.transition.plan':
exactObject(
value.request,
['assignments', 'packageName', 'projectId'],
@@ -637,6 +683,7 @@ function normalizeCommand(value: unknown): Readonly<LocalPluginPackageCommand> {
}
break;
case 'plugin-package.secret-binding.execute':
case 'plugin-package.secret-binding.transition.execute':
exactObject(
value.request,
['auditEventId', 'plan'],
@@ -653,7 +700,11 @@ function normalizeCommand(value: unknown): Readonly<LocalPluginPackageCommand> {
);
}
try {
normalizePluginPackageSecretBindingPlan(value.request.plan);
if (value.operation === 'plugin-package.secret-binding.execute') {
normalizePluginPackageSecretBindingPlan(value.request.plan);
} else {
normalizePluginPackageSecretBindingTransitionPlan(value.request.plan);
}
} catch (error) {
throw new LocalPluginPackageCommandConfigurationError(
'Secret binding plan is invalid',
@@ -851,6 +902,43 @@ function secretBindingPlanSummary(
});
}
function secretBindingTransitionPlanSummary(
plan: Readonly<PluginPackageSecretBindingTransitionPlan>,
) {
return Object.freeze({
kind: plan.kind,
projectId: plan.nextTarget.projectId,
packageName: plan.nextTarget.packageName,
previousInstallationId: plan.previousTarget.installationId,
previousGeneration: plan.previousTarget.generation,
previousGenerationDigest: plan.previousTarget.generationDigest,
previousBindingDigest: plan.previousBinding?.bindingDigest ?? null,
previousAttemptGeneration: plan.previousAttemptGeneration,
installationId: plan.nextTarget.installationId,
generation: plan.nextTarget.generation,
generationDigest: plan.nextTarget.generationDigest,
manifestDigest: plan.nextTarget.manifestDigest,
bindingRequired: plan.nextBindingPlan !== null,
assignments:
plan.nextBindingPlan?.entries.map((entry) =>
Object.freeze({
name: entry.name,
required: entry.required,
bound: entry.secretRef !== null,
secretRef: entry.secretRef,
}),
) ?? Object.freeze([]),
changes: plan.changes.map((change) =>
Object.freeze({
name: change.name,
requirement: change.requirement,
reference: change.reference,
}),
),
transitionDigest: plan.transitionDigest,
});
}
async function execute(
command: Readonly<LocalPluginPackageCommand>,
database: LocalSqlitePluginPackageManagementDatabase,
@@ -873,6 +961,22 @@ async function execute(
summary: secretBindingPlanSummary(plan),
});
}
if (command.operation === 'plugin-package.secret-binding.transition.plan') {
const service = createLocalPluginPackageSecretBindingService(
database.authority,
);
const plan = await service.planTransition({
...command.request,
principal: authenticated.principal,
plannedAtMs: Date.now(),
});
return Object.freeze({
schemaVersion: 1,
operation: command.operation,
plan,
summary: secretBindingTransitionPlanSummary(plan),
});
}
if (command.operation === 'plugin-package.secret-binding.execute') {
const service = createLocalPluginPackageSecretBindingService(
database.authority,
@@ -888,6 +992,23 @@ async function execute(
...result,
});
}
if (
command.operation === 'plugin-package.secret-binding.transition.execute'
) {
const service = createLocalPluginPackageSecretBindingService(
database.authority,
);
const result = await service.executeTransition({
...command.request,
principal: authenticated.principal,
confirmAuthorization: authenticated.confirm,
});
return Object.freeze({
schemaVersion: 1,
operation: command.operation,
...result,
});
}
if (command.operation === 'plugin-package.lifecycle.plan') {
const service = createLocalPluginPackageLifecycleService({
authority: database.authority,
packages/ql3-local-owner-cli/test/localDeployment.test.cjs
+11 -11
View File
@@ -363,9 +363,9 @@ function composeDockerHarness(
'/opt/qinglong/node_modules/@qinglong/local-application/dist/cli.js',
],
Labels: {
'io.qinglong.local.sqlite-contract-min': '48',
'io.qinglong.local.sqlite-contract-max': '48',
'io.qinglong.local.sqlite-write-contract': '48',
'io.qinglong.local.sqlite-contract-min': '49',
'io.qinglong.local.sqlite-contract-max': '49',
'io.qinglong.local.sqlite-write-contract': '49',
'io.qinglong.local.application-config': '2',
'io.qinglong.local.compose-selection': '1',
'io.qinglong.ai': 'excluded',
@@ -975,9 +975,9 @@ test('preflights exact local image, Compose merge and SQLite capability', async
'/opt/qinglong/node_modules/@qinglong/local-application/dist/cli.js',
],
Labels: {
'io.qinglong.local.sqlite-contract-min': '48',
'io.qinglong.local.sqlite-contract-max': '48',
'io.qinglong.local.sqlite-write-contract': '48',
'io.qinglong.local.sqlite-contract-min': '49',
'io.qinglong.local.sqlite-contract-max': '49',
'io.qinglong.local.sqlite-write-contract': '49',
'io.qinglong.local.application-config': '2',
'io.qinglong.local.compose-selection': '1',
'io.qinglong.ai': 'excluded',
@@ -1029,7 +1029,7 @@ test('preflights exact local image, Compose merge and SQLite capability', async
assert.equal(result.status, 'ready');
assert.equal(result.generation, 1);
assert.equal(result.profile, 'edge');
assert.equal(result.sqlite.contractVersion, 48);
assert.equal(result.sqlite.contractVersion, 49);
assert.equal(result.image.architecture, 'arm64');
assert.equal(calls.length, 2);
assert.deepEqual(calls[0].slice(0, 2), ['image', 'inspect']);
@@ -1129,8 +1129,8 @@ test('applies one Compose generation and exactly replays its health receipt', as
assert.equal(mode(receiptPath), 0o600);
const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
assert.deepEqual(receipt.sqlite, {
contractVersion: 48,
writeContractVersion: 48,
contractVersion: 49,
writeContractVersion: 49,
writeObservation: 'unchanged',
backup: null,
});
@@ -1427,8 +1427,8 @@ test('rolls a failed Compose candidate forward to a healthy prior digest', async
`${command.request.rolloutId}.sqlite`,
);
assert.equal(mode(backupPath), 0o600);
assert.equal(receipt.sqlite.contractVersion, 48);
assert.equal(receipt.sqlite.writeContractVersion, 48);
assert.equal(receipt.sqlite.contractVersion, 49);
assert.equal(receipt.sqlite.writeContractVersion, 49);
assert.equal(receipt.sqlite.writeObservation, 'changed');
assert.match(receipt.sqlite.backup.sha256, /^[0-9a-f]{64}$/);
assert.equal(receipt.sqlite.backup.bytes > 0, true);
packages/ql3-local-owner-cli/test/localReadiness.test.cjs
+2 -2
View File
@@ -34,8 +34,8 @@ test('inspects the exact fresh Profile schema without exposing its path', async
assert.equal(result.status, 'ready');
assert.equal(result.profile, 'edge');
assert.equal(result.storage.contractName, 'local-control-core');
assert.equal(result.storage.contractVersion, 48);
assert.equal(result.storage.migrationCount, 96);
assert.equal(result.storage.contractVersion, 49);
assert.equal(result.storage.migrationCount, 98);
assert.equal(result.storage.journalMode, 'delete');
assert.equal(JSON.stringify(result).includes(state.directory), false);
});
packages/ql3-local-owner-cli/test/pluginPackageCommand.test.cjs
+353
View File
@@ -41,6 +41,9 @@ const { migrateLocalSqlitePath } = require('@qinglong/local-sqlite/migration');
const {
LocalSqlitePluginPackageInstallRepository,
} = require('@qinglong/local-sqlite/plugin-package-install');
const {
LocalSqlitePluginPackageSecretBindingActivationPrerequisite,
} = require('@qinglong/local-sqlite/plugin-package-secret-binding-activation-prerequisite');
const {
LocalSqlitePluginPackageAutomationPublicationRepository,
} = require('@qinglong/local-sqlite/plugin-package-automation-publication');
@@ -72,10 +75,14 @@ const {
} = require('@qinglong/runtime-core/plugin-package-bundle');
const {
serializePluginPackageManifest,
createPluginPackageActivationReceipt,
pluginPackageActivationIntentDigest,
pluginPackageInstallCommit,
transitionPluginPackageInstall,
} = require('@qinglong/runtime-core/plugin-package-install');
const {
PluginPackageRecoveryCoordinator,
} = require('@qinglong/runtime-core/plugin-package-recovery');
const {
createInitialPluginPackageAutomationPublication,
} = require('@qinglong/runtime-core/plugin-package-automation-publication');
@@ -273,6 +280,38 @@ function actionInput(secretAware = false) {
};
}
function upgradeActionInput(previousInput, previousLockDigest) {
const manifest = {
...previousInput.manifest,
metadata: {
...previousInput.manifest.metadata,
version: '1.1.0',
description: 'One bounded upgraded package',
},
};
const artifact = packageArtifact(manifest);
const artifactDigest = digest(artifact);
return {
...previousInput,
lockId: 'cli-monitor-v2',
manifest,
plan: planPluginPackageInstall(
manifest,
previousInput.environment,
previousInput.manifest,
),
previousManifest: previousInput.manifest,
source: {
...previousInput.source,
locator: `offline:sha256:${artifactDigest}`,
artifactDigest,
artifactBytes: artifact.byteLength,
},
targetGeneration: 2,
previousLockDigest,
};
}
async function fixture(t, owner = true) {
const deploymentRoot = fs.realpathSync(
fs.mkdtempSync(path.join(os.tmpdir(), 'ql3-package-command-')),
@@ -550,6 +589,30 @@ async function activatePackageOnly(databasePath, projectId, packageName) {
}
}
async function stagePackageOnly(databasePath, projectId, packageName) {
const client = new DatabaseSync(databasePath);
const authority = new LocalSqliteOperationAuthority(client);
try {
const installs = new LocalSqlitePluginPackageInstallRepository(authority);
const queued = await installs.find(projectId, packageName);
const lock = await installs.findLock(queued.lockDigest);
const staged = transitionPluginPackageInstall(lock, queued, {
type: 'stage_completed',
mutationId: `secret-binding-stage-package-${queued.targetGeneration}`,
occurredAtMs: queued.updatedAtMs + 1,
stageRef: `stage:${lock.lockDigest}`,
artifactDigest: lock.source.artifactDigest,
manifestDigest: lock.manifestDigest,
contentDigest: lock.source.contentDigest,
evidenceDigest: 'e'.repeat(64),
});
await installs.commit(pluginPackageInstallCommit(queued, staged));
return { staged, lock };
} finally {
await authority.close();
}
}
function publisherTrustRunnerWithOneSnapshotFault() {
let injectFault = true;
return createLocalPluginPackagePublisherTrustCommandRunner({
@@ -1662,6 +1725,296 @@ test('plans and atomically binds a versioned Secret to the current Package gener
}
});
test('keeps an upgrade staged until the Owner commits its Secret transition', async (t) => {
const value = await fixture(t);
const initialInput = actionInput(true);
const initialActionRef = 'proposal:transition-cli-monitor-v1';
const initialApprovalId = 'approval-transition-cli-monitor-v1';
await runLocalPluginPackageCommandFile(
commandFile(
value,
'plugin-package.propose',
{
actionRef: initialActionRef,
approvalRequestId: initialApprovalId,
proposalAuditEventId: '22000000-0000-4000-8000-000000000001',
approvalAuditEventId: '22000000-0000-4000-8000-000000000002',
actionInput: initialInput,
},
'transition-01-propose',
),
);
await runLocalPluginPackageCommandFile(
commandFile(
value,
'plugin-package.decide',
{
actionRef: initialActionRef,
approvalRequestId: initialApprovalId,
expectedVersion: 1,
decisionId: 'decision-transition-cli-monitor-v1',
auditEventId: '22000000-0000-4000-8000-000000000003',
decision: 'approved',
reasonCode: 'reviewed',
},
'transition-02-decide',
),
);
await runLocalPluginPackageCommandFile(
commandFile(
value,
'plugin-package.consume',
{
actionRef: initialActionRef,
approvalRequestId: initialApprovalId,
expectedVersion: 2,
consumptionId: 'consume-transition-cli-monitor-v1',
dispatchId: 'dispatch-transition-cli-monitor-v1',
auditEventId: '22000000-0000-4000-8000-000000000004',
},
'transition-03-consume',
),
);
await runLocalPluginPackageCommandFile(
commandFile(
value,
'plugin-package.dispatch',
{ limit: 1 },
'transition-04-dispatch',
),
);
const { active, lock: activeLock } = await activatePackageOnly(
value.databasePath,
'default',
'cli-monitor',
);
const secretRef = createSecretRef({
projectId: 'default',
name: 'transition-token',
version: 1,
});
const database = new DatabaseSync(value.databasePath);
try {
database
.prepare(
`INSERT INTO "QingLong3LocalSecretEnvelopes" (
"project_id", "secret_name", "version", "mutation_id",
"key_id", "algorithm", "nonce", "ciphertext", "auth_tag",
"created_at_ms"
) VALUES (?, ?, 1, ?, ?, 'aes-256-gcm', ?, ?, ?, ?)`,
)
.run(
'default',
'transition-token',
'transition-secret-v1',
'fixture-key-v1',
Buffer.alloc(12, 3),
Buffer.from('ciphertext'),
Buffer.alloc(16, 4),
Date.now(),
);
} finally {
database.close();
}
const initialPlan = await runLocalPluginPackageCommandFile(
commandFile(
value,
'plugin-package.secret-binding.plan',
{
projectId: 'default',
packageName: 'cli-monitor',
assignments: [{ name: 'TOKEN', secretRef }],
},
'transition-05-bind-plan',
),
);
await runLocalPluginPackageCommandFile(
commandFile(
value,
'plugin-package.secret-binding.execute',
{
plan: initialPlan.plan,
auditEventId: '22000000-0000-4000-8000-000000000005',
},
'transition-06-bind-execute',
),
);
const upgradeInput = upgradeActionInput(initialInput, activeLock.lockDigest);
const upgradeActionRef = 'proposal:transition-cli-monitor-v2';
const upgradeApprovalId = 'approval-transition-cli-monitor-v2';
await runLocalPluginPackageCommandFile(
commandFile(
value,
'plugin-package.propose',
{
actionRef: upgradeActionRef,
approvalRequestId: upgradeApprovalId,
proposalAuditEventId: '22000000-0000-4000-8000-000000000006',
approvalAuditEventId: '22000000-0000-4000-8000-000000000007',
actionInput: upgradeInput,
},
'transition-07-upgrade-propose',
),
);
await runLocalPluginPackageCommandFile(
commandFile(
value,
'plugin-package.decide',
{
actionRef: upgradeActionRef,
approvalRequestId: upgradeApprovalId,
expectedVersion: 1,
decisionId: 'decision-transition-cli-monitor-v2',
auditEventId: '22000000-0000-4000-8000-000000000008',
decision: 'approved',
reasonCode: 'reviewed',
},
'transition-08-upgrade-decide',
),
);
await runLocalPluginPackageCommandFile(
commandFile(
value,
'plugin-package.consume',
{
actionRef: upgradeActionRef,
approvalRequestId: upgradeApprovalId,
expectedVersion: 2,
consumptionId: 'consume-transition-cli-monitor-v2',
dispatchId: 'dispatch-transition-cli-monitor-v2',
auditEventId: '22000000-0000-4000-8000-000000000009',
},
'transition-09-upgrade-consume',
),
);
await runLocalPluginPackageCommandFile(
commandFile(
value,
'plugin-package.dispatch',
{ limit: 1 },
'transition-10-upgrade-dispatch',
),
);
const { staged } = await stagePackageOnly(
value.databasePath,
'default',
'cli-monitor',
);
const recoveryClient = new DatabaseSync(value.databasePath);
const recoveryAuthority = new LocalSqliteOperationAuthority(recoveryClient);
const installs = new LocalSqlitePluginPackageInstallRepository(
recoveryAuthority,
);
const published = [];
let publishedReceipt;
const activationPrerequisite =
new LocalSqlitePluginPackageSecretBindingActivationPrerequisite(
recoveryAuthority,
);
const recovery = new PluginPackageRecoveryCoordinator({
repository: installs,
stageProvider: {
async stage() {
throw new Error('staged upgrade must not be staged twice');
},
},
publisher: {
async publish(intent) {
published.push(intent.intentDigest);
const receipt = createPluginPackageActivationReceipt({
activationRef: `activation:${intent.lockDigest}`,
intentDigest: intent.intentDigest,
generation: intent.targetGeneration,
contentDigest: intent.contentDigest,
activatedAtMs: staged.updatedAtMs + 2,
});
publishedReceipt = receipt;
return receipt;
},
async inspect() {
return publishedReceipt
? { status: 'published', receipt: publishedReceipt }
: { status: 'not_published' };
},
},
activationPrerequisite,
now: () => staged.updatedAtMs + 1,
});
assert.deepEqual(
await activationPrerequisite.inspect(
staged,
await installs.findLock(staged.lockDigest),
),
{
status: 'deferred',
reason: 'secret_binding_transition_required',
},
);
const deferred = await recovery.recover({ pageSize: 1, maxPages: 1 });
assert.equal(deferred.scanned, 0);
assert.equal(deferred.safeToAdmit, true);
assert.equal((await installs.find('default', 'cli-monitor')).state, 'staged');
assert.deepEqual(published, []);
const transitionPlan = await runLocalPluginPackageCommandFile(
commandFile(
value,
'plugin-package.secret-binding.transition.plan',
{
projectId: 'default',
packageName: 'cli-monitor',
assignments: [{ name: 'TOKEN', secretRef }],
},
'transition-11-plan',
),
);
assert.equal(transitionPlan.summary.generation, 2);
assert.equal(transitionPlan.summary.kind, 'carry-forward');
const executePath = commandFile(
value,
'plugin-package.secret-binding.transition.execute',
{
plan: transitionPlan.plan,
auditEventId: '22000000-0000-4000-8000-00000000000a',
},
'transition-12-execute',
);
const created = await runLocalPluginPackageCommandFile(executePath);
assert.equal(created.status, 'created');
assert.match(created.receiptDigest, /^[0-9a-f]{64}$/);
assert.equal(
(await runLocalPluginPackageCommandFile(executePath)).status,
'existing',
);
const settled = await recovery.recoverPage({ limit: 1 });
const recovered = await installs.find('default', 'cli-monitor');
assert.equal(settled.items[0].status, 'settled');
assert.equal(
recovered.state,
'active',
JSON.stringify({ recovered, publishedReceipt }),
);
assert.equal(published.length, 1);
const inspection = new DatabaseSync(value.databasePath, { readOnly: true });
try {
assert.equal(
inspection
.prepare(
`SELECT COUNT(*) AS count
FROM "QingLong3PluginPackageSecretBindingTransitionReceipts"`,
)
.get().count,
1,
);
} finally {
inspection.close();
await recoveryAuthority.close();
}
assert.equal(active.state, 'active');
});
test('denies an authenticated non-owner before package proposal mutation', async (t) => {
const value = await fixture(t, false);
await assert.rejects(