create-qpq-app 0.1.23 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Scaffold a new quidproquo app: npx create-qpq-app my-app",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/esm/index.js",
@@ -55,7 +55,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.13",
-    "quidproquo-tsconfig": "0.1.23"
+    "quidproquo-tsconfig": "0.1.25"
   },
   "bin": {
     "create-qpq-app": "./lib/commonjs/bin/createQpqApp.js"

package/template/apps/qpqjs/packages/constants/src/smokeProbe.ts

@@ -4,6 +4,9 @@
 export const SMOKE_PROBE_STORE = 'smokeProbe';
 // Lowercase with a hyphen: this becomes an S3 bucket name, which must be lowercase.
 export const SMOKE_PROBE_DRIVE = 'smoke-probe';
+// The signing key the test service owns. testa declares it foreign and
+// verifies tokens the test service signed with it.
+export const SMOKE_PROBE_SIGNING_KEY = 'smokeProbe';
 
 // The testa service functions the cross-service smoke tests invoke, one per
 // foreign grant (the store and the drive are separate IAM statements).
@@ -11,3 +14,5 @@ export const SMOKE_CROSS_SERVICE_KEY_VALUE_STORE_PROBE_FUNCTION_NAME =
   'crossKvsProbe';
 export const SMOKE_CROSS_SERVICE_STORAGE_DRIVE_PROBE_FUNCTION_NAME =
   'crossDriveProbe';
+export const SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME =
+  'crossSigningKeyProbe';

package/template/apps/qpqjs/services/test/models/src/SmokeSigningKeyClaims.ts

@@ -0,0 +1,6 @@
+// The claims the signing-key smoke tests mint. `runId` ties a token to the run
+// that minted it; `exp` is a JWT NumericDate the verifier checks against QPQ time.
+export type SmokeSigningKeyClaims = {
+  runId: string;
+  exp: number;
+};

package/template/apps/qpqjs/services/test/models/src/index.ts

@@ -6,5 +6,6 @@ export * from './SmokeRunStarted';
 export * from './SmokeRunStatus';
 export * from './SmokeRunSummary';
 export * from './SmokeRunWithSummary';
+export * from './SmokeSigningKeyClaims';
 export * from './SmokeTestResult';
 export * from './SmokeTestStatus';

package/template/apps/qpqjs/services/test/service/src/smoke/config/defineSmoke.ts

@@ -5,6 +5,7 @@ import {
   defineQueue,
   defineRoute,
   defineSecret,
+  defineSigningKey,
   defineStorageDrive,
   QPQConfig,
   QpqFunctionRuntime,
@@ -12,7 +13,11 @@ import {
 import { defineEventDoc } from 'quidproquo-features';
 
 import { z } from 'zod/v4';
-import { SMOKE_PROBE_DRIVE, SMOKE_PROBE_STORE } from '@qpqjs/constants';
+import {
+  SMOKE_PROBE_DRIVE,
+  SMOKE_PROBE_SIGNING_KEY,
+  SMOKE_PROBE_STORE,
+} from '@qpqjs/constants';
 import {
   SmokeProbeRecord,
   SmokeRunStartedSchema,
@@ -83,6 +88,10 @@ export const defineSmoke = (): QPQConfig => {
     }),
     defineSecret(SMOKE_PROBE_SECRET),
     defineStorageDrive(SMOKE_PROBE_DRIVE),
+    // An owned RSA signing key: kms:Sign + kms:GetPublicKey through the
+    // alias-conditioned grant. testa declares the same key foreign (see
+    // defineCrossServiceProbe) for the cross-service verify test.
+    defineSigningKey(SMOKE_PROBE_SIGNING_KEY),
 
     // Event bus test path: publish to the bus, the subscribed queue's entry
     // writes a marker into the probe store, the test polls for it.

package/template/apps/qpqjs/services/test/service/src/smoke/tests/crossService/askRunCrossServiceSigningKeyTest.ts

@@ -0,0 +1,60 @@
+import {
+  askCryptoGetPublicKey,
+  askCryptoSignJwt,
+  askGetCurrentEpoch,
+  AskResponse,
+  askServiceFunctionExecute,
+} from 'quidproquo';
+
+import {
+  QpqjsServiceEnum,
+  SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME,
+  SMOKE_PROBE_SIGNING_KEY,
+} from '@qpqjs/constants';
+import { SmokeSigningKeyClaims } from '@qpqjs/test-models';
+import {
+  CrossServiceSigningKeyProbePayload,
+  CrossServiceSigningKeyProbeResult,
+} from '@qpqjs/testa-models';
+
+import { askSmokeAssert } from '../askSmokeAssert';
+
+// The issuer/verifier split a signing key exists for: THIS service signs a
+// jwt with its owned key, testa verifies it through its foreign declaration
+// (owner: test) of the same key. An error from inside testa is its
+// kms:GetPublicKey grant or the cross-module alias resolution; a valid result
+// with our runId proves both services resolved the same physical key, which
+// the public key comparison then confirms directly. testa also tries to sign
+// with the key: a foreign declaration holds no kms:Sign, so that must fail.
+export function* askRunCrossServiceSigningKeyTest(
+  runId: string
+): AskResponse<void> {
+  const now = yield* askGetCurrentEpoch();
+  const claims: SmokeSigningKeyClaims = { runId, exp: now + 60 };
+  const token = yield* askCryptoSignJwt(SMOKE_PROBE_SIGNING_KEY, claims);
+
+  const result = yield* askServiceFunctionExecute<
+    CrossServiceSigningKeyProbeResult,
+    CrossServiceSigningKeyProbePayload
+  >(
+    QpqjsServiceEnum.TestA,
+    SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME,
+    { token }
+  );
+
+  yield* askSmokeAssert(
+    result.runId === runId,
+    `testa did not verify our jwt (${result.runId ?? 'invalid'})`
+  );
+
+  const publicKeyPem = yield* askCryptoGetPublicKey(SMOKE_PROBE_SIGNING_KEY);
+  yield* askSmokeAssert(
+    result.publicKeyPem === publicKeyPem,
+    'testa resolved a different public key than the owning service'
+  );
+
+  yield* askSmokeAssert(
+    !result.couldSign,
+    'testa was able to sign with a key it does not own'
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/tests/crossService/index.ts

@@ -1,2 +1,3 @@
 export * from './askRunCrossServiceKeyValueStoreTest';
+export * from './askRunCrossServiceSigningKeyTest';
 export * from './askRunCrossServiceStorageDriveTest';

package/template/apps/qpqjs/services/test/service/src/smoke/tests/index.ts

@@ -7,6 +7,7 @@ export * from './noop';
 export * from './openApi';
 export * from './parameter';
 export * from './secret';
+export * from './signingKey';
 export * from './SmokeTestDefinition';
 export * from './smokeTestRegistry';
 export * from './storageDrive';

package/template/apps/qpqjs/services/test/service/src/smoke/tests/signingKey/askRunSigningKeyTest.ts

@@ -0,0 +1,87 @@
+import {
+  askCryptoGetPublicKey,
+  askCryptoSign,
+  askCryptoSignJwt,
+  askCryptoVerify,
+  askCryptoVerifyJwt,
+  askGetCurrentEpoch,
+  AskResponse,
+} from 'quidproquo';
+
+import { SMOKE_PROBE_SIGNING_KEY } from '@qpqjs/constants';
+import { SmokeSigningKeyClaims } from '@qpqjs/test-models';
+
+import { askSmokeAssert } from '../askSmokeAssert';
+
+const PUBLIC_KEY_PEM_HEADER = '-----BEGIN PUBLIC KEY-----';
+
+// Every signing-key action against the owned key: kms:Sign (askCryptoSign /
+// askCryptoSignJwt) and kms:GetPublicKey (askCryptoGetPublicKey, and the
+// in-process askCryptoVerify behind askCryptoVerifyJwt). Then the two ways a
+// token must fail - a flipped signature byte and a past exp - so a verifier
+// that accepts everything cannot pass.
+export function* askRunSigningKeyTest(runId: string): AskResponse<void> {
+  const publicKeyPem = yield* askCryptoGetPublicKey(SMOKE_PROBE_SIGNING_KEY);
+  yield* askSmokeAssert(
+    publicKeyPem.startsWith(PUBLIC_KEY_PEM_HEADER),
+    'GetPublicKey did not return an SPKI PEM'
+  );
+
+  const message = `smoke probe ${runId}`;
+  const signature = yield* askCryptoSign(SMOKE_PROBE_SIGNING_KEY, message);
+  yield* askSmokeAssert(
+    signature.length > 0,
+    'Sign returned an empty signature'
+  );
+
+  const verified = yield* askCryptoVerify(
+    SMOKE_PROBE_SIGNING_KEY,
+    message,
+    signature
+  );
+  yield* askSmokeAssert(verified, 'raw signature did not verify');
+
+  const now = yield* askGetCurrentEpoch();
+
+  const claims: SmokeSigningKeyClaims = { runId, exp: now + 60 };
+  const token = yield* askCryptoSignJwt(SMOKE_PROBE_SIGNING_KEY, claims);
+
+  const result = yield* askCryptoVerifyJwt<SmokeSigningKeyClaims>(
+    SMOKE_PROBE_SIGNING_KEY,
+    token
+  );
+  yield* askSmokeAssert(
+    result.valid && result.claims.runId === runId,
+    'signed jwt did not verify with its own claims'
+  );
+
+  // Corrupt a character in the MIDDLE of the signature segment. Not the last
+  // one: a 2048-bit signature is 342 base64url chars and the final char
+  // carries only two real bits, so flipping it can leave the decoded bytes
+  // unchanged and the token still valid.
+  const [header, payload, signatureSegment] = token.split('.');
+  const middle = Math.floor(signatureSegment.length / 2);
+  const flipped = signatureSegment[middle] === 'A' ? 'B' : 'A';
+  const tamperedToken = `${header}.${payload}.${signatureSegment.slice(0, middle)}${flipped}${signatureSegment.slice(middle + 1)}`;
+  const tampered = yield* askCryptoVerifyJwt<SmokeSigningKeyClaims>(
+    SMOKE_PROBE_SIGNING_KEY,
+    tamperedToken
+  );
+  yield* askSmokeAssert(
+    !tampered.valid && tampered.reason === 'bad-signature',
+    'tampered jwt was not rejected as bad-signature'
+  );
+
+  const expiredToken = yield* askCryptoSignJwt(SMOKE_PROBE_SIGNING_KEY, {
+    runId,
+    exp: now - 60,
+  });
+  const expired = yield* askCryptoVerifyJwt<SmokeSigningKeyClaims>(
+    SMOKE_PROBE_SIGNING_KEY,
+    expiredToken
+  );
+  yield* askSmokeAssert(
+    !expired.valid && expired.reason === 'expired',
+    'expired jwt was not rejected as expired'
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/tests/signingKey/index.ts

@@ -0,0 +1 @@
+export * from './askRunSigningKeyTest';

package/template/apps/qpqjs/services/test/service/src/smoke/tests/smokeTestRegistry.ts

@@ -1,4 +1,5 @@
 import { askRunCrossServiceKeyValueStoreTest } from './crossService/askRunCrossServiceKeyValueStoreTest';
+import { askRunCrossServiceSigningKeyTest } from './crossService/askRunCrossServiceSigningKeyTest';
 import { askRunCrossServiceStorageDriveTest } from './crossService/askRunCrossServiceStorageDriveTest';
 import { askRunEventBusTest } from './eventBus/askRunEventBusTest';
 import { askRunEventDocConcurrentAppendTest } from './eventDoc/askRunEventDocConcurrentAppendTest';
@@ -10,6 +11,7 @@ import { askRunOpenApiDocumentTest } from './openApi/askRunOpenApiDocumentTest';
 import { askRunParameterTest } from './parameter/askRunParameterTest';
 import { askRunScheduleTest } from './schedule/askRunScheduleTest';
 import { askRunSecretTest } from './secret/askRunSecretTest';
+import { askRunSigningKeyTest } from './signingKey/askRunSigningKeyTest';
 import { askRunStorageDriveTest } from './storageDrive/askRunStorageDriveTest';
 import { SmokeTestDefinition } from './SmokeTestDefinition';
 
@@ -44,4 +46,9 @@ export const smokeTestRegistry: SmokeTestDefinition[] = [
     name: 'eventDocInterleavedBatchAppend',
     askRun: askRunEventDocInterleavedBatchAppendTest,
   },
+  { name: 'signingKey', askRun: askRunSigningKeyTest },
+  {
+    name: 'crossServiceSigningKey',
+    askRun: askRunCrossServiceSigningKeyTest,
+  },
 ];

package/template/apps/qpqjs/services/testa/models/src/CrossServiceSigningKeyProbePayload.ts

@@ -0,0 +1,5 @@
+// Input to testa's smokeCrossServiceSigningKeyProbe service function: a jwt
+// the test service signed with its owned signing key.
+export type CrossServiceSigningKeyProbePayload = {
+  token: string;
+};

package/template/apps/qpqjs/services/testa/models/src/CrossServiceSigningKeyProbeResult.ts

@@ -0,0 +1,11 @@
+import { Nullable } from 'quidproquo';
+
+// What testa made of the token through its foreign declaration of the test
+// service's signing key: the runId claim when the jwt verified (null when it
+// did not), the public key it resolved so the caller can compare it with its
+// own, and whether it was ALLOWED to sign with the key - it must not be.
+export type CrossServiceSigningKeyProbeResult = {
+  runId: Nullable<string>;
+  publicKeyPem: string;
+  couldSign: boolean;
+};

package/template/apps/qpqjs/services/testa/models/src/index.ts

@@ -1,3 +1,5 @@
 export * from './CrossServiceKeyValueStoreProbeResult';
 export * from './CrossServiceProbePayload';
+export * from './CrossServiceSigningKeyProbePayload';
+export * from './CrossServiceSigningKeyProbeResult';
 export * from './CrossServiceStorageDriveProbeResult';

package/template/apps/qpqjs/services/testa/service/src/crossServiceProbe/config/defineCrossServiceProbe.ts

@@ -1,6 +1,7 @@
 import {
   defineKeyValueStore,
   defineServiceFunction,
+  defineSigningKey,
   defineStorageDrive,
   QPQConfig,
 } from 'quidproquo';
@@ -8,8 +9,10 @@ import {
 import {
   QpqjsServiceEnum,
   SMOKE_CROSS_SERVICE_KEY_VALUE_STORE_PROBE_FUNCTION_NAME,
+  SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME,
   SMOKE_CROSS_SERVICE_STORAGE_DRIVE_PROBE_FUNCTION_NAME,
   SMOKE_PROBE_DRIVE,
+  SMOKE_PROBE_SIGNING_KEY,
   SMOKE_PROBE_STORE,
 } from '@qpqjs/constants';
 import { SmokeProbeRecord } from '@qpqjs/test-models';
@@ -27,6 +30,10 @@ export const defineCrossServiceProbe = (): QPQConfig => {
       owner,
     }),
     defineStorageDrive(SMOKE_PROBE_DRIVE, { owner }),
+    // The signing key is the one foreign resource whose grant is alias-
+    // conditioned rather than exact-ARN: the owner's alias name is what this
+    // declaration must resolve to, or GetPublicKey is denied.
+    defineSigningKey(SMOKE_PROBE_SIGNING_KEY, { owner }),
 
     // One service function per foreign grant, invoked by the test service's
     // crossService* smoke tests.
@@ -48,5 +55,14 @@ export const defineCrossServiceProbe = (): QPQConfig => {
       },
       { functionName: SMOKE_CROSS_SERVICE_STORAGE_DRIVE_PROBE_FUNCTION_NAME }
     ),
+    defineServiceFunction(
+      {
+        basePath: __dirname,
+        relativePath:
+          '../entry/serviceFunction/smokeCrossServiceSigningKeyProbe',
+        functionName: 'smokeCrossServiceSigningKeyProbe',
+      },
+      { functionName: SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME }
+    ),
   ];
 };

package/template/apps/qpqjs/services/testa/service/src/crossServiceProbe/entry/serviceFunction/index.ts

@@ -1,2 +1,3 @@
 export * from './smokeCrossServiceKeyValueStoreProbe';
+export * from './smokeCrossServiceSigningKeyProbe';
 export * from './smokeCrossServiceStorageDriveProbe';

package/template/apps/qpqjs/services/testa/service/src/crossServiceProbe/entry/serviceFunction/smokeCrossServiceSigningKeyProbe.ts

@@ -0,0 +1,16 @@
+import { AskResponse, ExecuteServiceFunctionEvent } from 'quidproquo';
+
+import {
+  CrossServiceSigningKeyProbePayload,
+  CrossServiceSigningKeyProbeResult,
+} from '@qpqjs/testa-models';
+
+import { askProbeForeignSigningKey } from '../../logic/askProbeForeignSigningKey';
+
+// Service function entry, called cross-service by the test service's
+// crossServiceSigningKey smoke test.
+export function* smokeCrossServiceSigningKeyProbe(
+  event: ExecuteServiceFunctionEvent<CrossServiceSigningKeyProbePayload>
+): AskResponse<CrossServiceSigningKeyProbeResult> {
+  return yield* askProbeForeignSigningKey(event.payload.token);
+}

package/template/apps/qpqjs/services/testa/service/src/crossServiceProbe/logic/askProbeForeignSigningKey.ts

@@ -0,0 +1,36 @@
+import {
+  askCatch,
+  askCryptoGetPublicKey,
+  askCryptoSign,
+  askCryptoVerifyJwt,
+  AskResponse,
+} from 'quidproquo';
+
+import { SMOKE_PROBE_SIGNING_KEY } from '@qpqjs/constants';
+import { SmokeSigningKeyClaims } from '@qpqjs/test-models';
+import { CrossServiceSigningKeyProbeResult } from '@qpqjs/testa-models';
+
+// Verifies a jwt the test service signed, under THIS service's role and
+// through its foreign (owner: test) declaration of the key: kms:GetPublicKey
+// on the owner's alias, then an in-process RS256 check. Then tries to sign
+// with the same key, which the foreign declaration must NOT be granted.
+export function* askProbeForeignSigningKey(
+  token: string
+): AskResponse<CrossServiceSigningKeyProbeResult> {
+  const result = yield* askCryptoVerifyJwt<SmokeSigningKeyClaims>(
+    SMOKE_PROBE_SIGNING_KEY,
+    token
+  );
+
+  const publicKeyPem = yield* askCryptoGetPublicKey(SMOKE_PROBE_SIGNING_KEY);
+
+  const signAttempt = yield* askCatch(
+    askCryptoSign(SMOKE_PROBE_SIGNING_KEY, 'must-be-denied')
+  );
+
+  return {
+    runId: result.valid ? result.claims.runId : null,
+    publicKeyPem,
+    couldSign: signAttempt.success,
+  };
+}

package/template/apps/qpqjs/services/testa/service/src/crossServiceProbe/logic/index.ts

@@ -1,2 +1,3 @@
 export * from './askProbeForeignKeyValueStore';
+export * from './askProbeForeignSigningKey';
 export * from './askProbeForeignStorageDrive';

package/template/docusaurus/docs/actions/core/ai/ask-ai-prompt-stream.md

@@ -42,7 +42,7 @@ The parameters are identical to [askAiPrompt](./ask-ai-prompt.md) — see there
 | --- | --- | --- |
 | `model` | `AiModel` | Which model to prompt. |
 | `prompt` | `string` | The user prompt. Ignored when `options.messages` is set. |
-| `options` | `AskAiPromptStreamOptions` | `{ system?, aiName?, messages?, reasoning?, caching? }` — same shape and meaning as [`AskAiPromptOptions`](./ask-ai-prompt.md#askaipromptoptions). |
+| `options` | `AskAiPromptStreamOptions` | `{ system?, aiName?, messages?, reasoning?, caching?, maxDurationMs?, maxSteps?, maxOutputTokens? }` — same shape and meaning as [`AskAiPromptOptions`](./ask-ai-prompt.md#askaipromptoptions). |
 
 ## Returns
 
@@ -92,7 +92,7 @@ Within a step, text / reasoning / tool-input events arrive as matched `*Start
 | `stop` | `stop` | The model completed its answer naturally. |
 | `length` | `length` | The response hit the output token limit. |
 | `contentFilter` | `content-filter` | The provider's content filter stopped the response. |
-| `toolCalls` | `tool-calls` | Generation stopped while the model still had tool calls in flight. On the final `Finish` part this means the turn was halted early by a stop condition (e.g. a step limit) rather than finishing naturally, and can be resumed by re-sending the recorded history. |
+| `toolCalls` | `tool-calls` | Generation stopped while the model still had tool calls in flight. On the final `Finish` part this means the turn was halted early by a stop condition (`maxSteps` or `maxDurationMs`) rather than finishing naturally, and can be resumed by re-sending the recorded history. |
 | `error` | `error` | The stream errored. |
 | `other` | `other` | The provider reported a reason outside this catalog. |
 | `unknown` | `unknown` | The provider reported no reason, or one this version does not recognise. |

package/template/docusaurus/docs/actions/core/ai/ask-ai-prompt.md

@@ -50,6 +50,9 @@ function* askAiPrompt(
 | `messages` | [`AiMessage[]`](#aimessage) | – | A full conversation history. When present, this is sent instead of `prompt`, letting you carry a multi-turn dialogue (including prior assistant turns and tool results). |
 | `reasoning` | [`AiReasoningConfig`](#aireasoningconfig) | – | Enables extended thinking. Its presence turns reasoning on; `budgetTokens` caps how many tokens the model may spend thinking before it answers (defaults to `4096` on AWS). |
 | `caching` | `boolean` | – | Marks the system prompt and the last message (or the last `messages` entry) with a Bedrock cache point, so a following call in the same conversation can read everything up to there from cache instead of reprocessing it. |
+| `maxSteps` | `number` | – | Cap on model/tool steps in one call. Unset means no cap: the loop runs until the model stops on its own or `maxDurationMs` trips. A client-side tool call (a tool with no executor) still halts it immediately. |
+| `maxOutputTokens` | `number` | provider default | Output token cap per model call. Bedrock defaults to 8192, which a reasoning block plus a large tool input can exceed; the step then finishes with `length` and the tool call arrives truncated. Raise it for agentic workloads (Claude Sonnet allows 64k). |
+| `maxDurationMs` | `number` | – | Wall-clock budget for the tool loop. Checked between steps, so the loop can overrun by one step; leave headroom. When it trips with tool calls still outstanding the result finishes with `toolCalls`, and re-sending the recorded history resumes the turn. Pair it with [askGetRuntimeRemainingTime](../system/ask-get-runtime-remaining-time.md) to stop before the platform deadline. |
 
 ### `AiModel`
 

package/template/docusaurus/docs/actions/core/crypto/_category_.json

@@ -2,6 +2,6 @@
   "label": "Crypto",
   "link": {
     "type": "generated-index",
-    "description": "Crypto actions encrypt and decrypt values with a key declared by defineCryptoKey. Envelope encryption with an optional context that binds ciphertext to the place it was created."
+    "description": "Crypto actions encrypt and decrypt values with a key declared by defineCryptoKey, and sign and verify messages or JWTs with an asymmetric key declared by defineSigningKey. The key material never leaves the provider."
   }
 }

package/template/docusaurus/docs/actions/core/crypto/ask-crypto-get-public-key.md

@@ -0,0 +1,51 @@
+---
+title: askCryptoGetPublicKey
+description: Read the public half of a signing key as an SPKI PEM, for third parties to verify with.
+---
+
+# askCryptoGetPublicKey
+
+Returns the public half of a [signing key](../../../config/core/signing-key.md) as an SPKI PEM string. It is not sensitive: it can only verify, never sign. Hand it to anyone who needs to check your signatures without calling back in, for example from a `/.well-known/jwks.json` route or a partner integration.
+
+- **Action type:** `CryptoActionType.GetPublicKey`
+- **On AWS:** `kms:GetPublicKey`, cached per runtime for an hour.
+- **On the dev server:** the public half of the locally seeded pair.
+
+```typescript
+import { askCryptoGetPublicKey } from 'quidproquo-core';
+
+export function* askGetTokenVerificationKey() {
+  return yield* askCryptoGetPublicKey('access-token-key');
+}
+```
+
+## Signature
+
+```typescript
+function* askCryptoGetPublicKey(
+  keyName: string,
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyName` | `string` | Name of the signing key, declared with [defineSigningKey](../../../config/core/signing-key.md) (or shared via its `owner` option). |
+
+## Returns
+
+`string`: the public key as a PEM block (`-----BEGIN PUBLIC KEY-----` … `-----END PUBLIC KEY-----`), SubjectPublicKeyInfo encoding, as accepted by every JWT library and `openssl`.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `askCryptoGetPublicKey.errorType.KeyNotConfigured` | No `defineSigningKey` with that name exists in the service config. |
+| `askCryptoGetPublicKey.errorType.KeyUnavailable` | The key exists in config but is disabled, deleted, or access was denied. |
+| `askCryptoGetPublicKey.errorType.Throttling` | The provider rate limit was exceeded; back off and retry. |
+
+## Related
+
+- [defineSigningKey](../../../config/core/signing-key.md): declares the key this action uses.
+- [askCryptoVerify](./ask-crypto-verify.md): verifies in-process without exposing the key.

package/template/docusaurus/docs/actions/core/crypto/ask-crypto-sign-jwt.md

@@ -0,0 +1,53 @@
+---
+title: askCryptoSignJwt
+description: Mint a compact RS256 JWT over a claims object with a signing key.
+---
+
+# askCryptoSignJwt
+
+Builds a compact JWT (`header.payload.signature`) over `claims`, signed RS256 with a [signing key](../../../config/core/signing-key.md). A story-level helper over [askCryptoSign](./ask-crypto-sign.md): the header is fixed at `{ "alg": "RS256", "typ": "JWT" }`, both segments are base64url, and the signature comes from the key's private half without it ever entering the story.
+
+Every time-based claim (`exp`, `nbf`, `iat`) must already be on `claims`, sourced from QPQ time, so the story stays deterministic. Nothing is added or rewritten.
+
+```typescript
+import { askCryptoSignJwt, askGetCurrentEpoch } from 'quidproquo-core';
+
+export function* askIssueAccessToken(clientId: string, grants: string[]) {
+  const now = yield* askGetCurrentEpoch();
+
+  return yield* askCryptoSignJwt('access-token-key', {
+    sub: clientId,
+    grants,
+    exp: now + 3600,
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askCryptoSignJwt(
+  keyName: string,
+  claims: object,
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyName` | `string` | Name of the signing key, declared with [defineSigningKey](../../../config/core/signing-key.md). |
+| `claims` | `object` | The JWT payload, serialised with `JSON.stringify`. Put `exp`/`nbf` here as unix seconds if you want [askCryptoVerifyJwt](./ask-crypto-verify-jwt.md) to enforce them. |
+
+## Returns
+
+`string`: the compact JWT.
+
+## Errors
+
+Those of [askCryptoSign](./ask-crypto-sign.md).
+
+## Related
+
+- [askCryptoVerifyJwt](./ask-crypto-verify-jwt.md): the matching verifier.
+- [defineSigningKey](../../../config/core/signing-key.md): declares the key.

package/template/docusaurus/docs/actions/core/crypto/ask-crypto-sign.md

@@ -0,0 +1,54 @@
+---
+title: askCryptoSign
+description: Sign a message with a signing key's private half and get back a base64url RS256 signature.
+---
+
+# askCryptoSign
+
+Signs a string with a [signing key](../../../config/core/signing-key.md) and returns the RS256 signature as unpadded base64url. The private key never leaves the provider; the story only ever sees the signature. Most stories want [askCryptoSignJwt](./ask-crypto-sign-jwt.md) instead, which builds the JWT framing around this.
+
+- **Action type:** `CryptoActionType.Sign`
+- **On AWS:** one `kms:Sign` call (`RSASSA_PKCS1_V1_5_SHA_256`) against the key provisioned by [defineSigningKey](../../../config/core/signing-key.md).
+- **On the dev server:** the same signature computed with Node's `crypto` against the locally seeded pair at `.qpq-runtime/<app>/signingKeys/<service>.json`.
+
+```typescript
+import { askCryptoSign } from 'quidproquo-core';
+
+export function* askSignWebhookBody(body: string) {
+  return yield* askCryptoSign('webhook-signing-key', body);
+}
+```
+
+## Signature
+
+```typescript
+function* askCryptoSign(
+  keyName: string,
+  message: string,
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyName` | `string` | Name of the signing key, declared with [defineSigningKey](../../../config/core/signing-key.md) (or shared via its `owner` option). |
+| `message` | `string` | The exact bytes (UTF-8) to sign. Verification must be given the identical string. |
+
+## Returns
+
+`string`: the signature, base64url encoded without padding. RS256 is deterministic, so the same key and message always return the same value.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `askCryptoSign.errorType.KeyNotConfigured` | No `defineSigningKey` with that name exists in the service config. |
+| `askCryptoSign.errorType.KeyUnavailable` | The key exists in config but is disabled, deleted, or access was denied. Infrastructure problem; surface to ops. |
+| `askCryptoSign.errorType.Throttling` | The provider rate limit was exceeded; back off and retry. |
+
+## Related
+
+- [defineSigningKey](../../../config/core/signing-key.md): declares the key this action uses.
+- [askCryptoVerify](./ask-crypto-verify.md): checks a signature.
+- [askCryptoSignJwt](./ask-crypto-sign-jwt.md): mints a JWT with this action.