@rdlabo/workers-hono-kit 0.6.3 → 0.6.4

package/README.md

@@ -5,7 +5,7 @@ Infrastructure toolkit for building APIs on [Hono](https://hono.dev) + [Cloudfla
 It provides the building blocks a NestJS-style API needs but that don't run on `workerd` (no Node.js AWS SDK, no `firebase-admin`), plus middleware that matches Express / NestJS response semantics byte-for-byte:
 
 - **Firebase ID-token verification** on Workers via [`jose`](https://github.com/panva/jose) (RS256 against Google's securetoken JWKS), with optional Identity Toolkit REST for `getUser` / `deleteUser`.
-- **AWS Secrets Manager** via SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) — no AWS SDK.
+- **AWS Secrets Manager / STS AssumeRole / CloudFront signed URLs** via SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) or Web Crypto — no AWS SDK.
 - **Middleware**: `finalizeResponse` (Express-compatible weak ETag + JSON charset), `validate` (NestJS `ValidationPipe`-shaped 400), and zod number-coercion helpers.
 - **Standard API errors**: `createHttpErrorHandler` / `notFoundHandler` / `HttpStatus`.
 - **Deadlock retry** (`ER_LOCK_DEADLOCK` exponential backoff) and an optional **MySQL data layer** (`@rdlabo/workers-hono-kit/db`) for Hyperdrive + Drizzle.
@@ -56,6 +56,7 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `createSentryValidate(sentry)` | **Deprecated** — use `createValidate({ sentry })`. |
 | `zNum` / `zNumWithDefault` / `zNumOptional` / `zNumNullable` | Number-coercion zod schemas (mirror class-transformer `@Transform`). |
 | `getAuthenticationSecret<T>(options, secretId)` / `AwsSecretsOptions` | Fetch a secret from AWS Secrets Manager (SigV4 `fetch`, per-isolate cache). |
+| `getTemporaryCredentials(options)` / `GetTemporaryCredentialsOptions` / `StsCredentials` | STS `AssumeRole` via SigV4 `fetch` (global `sts.amazonaws.com`); returns temporary credentials for browser S3 uploads. |
 | `getCloudFrontSignedUrl(url, privateKeyPem, keyPairId, dateLessThan)` | CloudFront signed URL (canned policy, RSA-SHA1, URL-safe base64) — Web Crypto reimpl of `@aws-sdk/cloudfront-signer`, byte-identical query order. |
 | `JoseFirebaseVerifier` / `FirebaseVerifier` / `DecodedIdToken` | Firebase ID-token verification (`verifyIdToken`, `getUser`, `deleteUser`). |
 | `createRemoteFirebaseVerifier(projectId)` | Convenience factory: production verifier with a cached remote JWKS (verification only). |
@@ -271,6 +272,20 @@ const secret = await getAuthenticationSecret<MySecret>(
 );
 ```
 
+### STS AssumeRole (browser S3 uploads)
+
+```ts
+import { getTemporaryCredentials } from '@rdlabo/workers-hono-kit';
+
+const credentials = await getTemporaryCredentials({
+  accessKeyId: env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+  roleArn: 'arn:aws:iam::123456789012:role/s3-put-app-only-role',
+  roleSessionName: `session-${userId}-${Date.now()}`,
+});
+// Return credentials to the browser; PutObject uses @aws-sdk/client-s3 with AccessKeyId / …
+```
+
 ### Deadlock retry & HTTP helpers
 
 ```ts

package/dist/aws/sts.d.ts

@@ -0,0 +1,67 @@
+/**
+ * AWS credentials used to sign an STS `AssumeRole` request.
+ *
+ * @remarks
+ * Same shape as {@link AwsSecretsOptions} minus the required Secrets Manager region; STS defaults to
+ * the global endpoint (`us-east-1`) unless {@link GetTemporaryCredentialsOptions.region} is set.
+ */
+export interface GetTemporaryCredentialsOptions {
+    /** AWS access key ID of the caller principal that may AssumeRole. */
+    accessKeyId: string;
+    /** AWS secret access key of the caller principal. */
+    secretAccessKey: string;
+    /** Optional STS session token when the caller already holds temporary credentials. */
+    sessionToken?: string;
+    /** ARN of the role to assume (e.g. `arn:aws:iam::123:role/s3-put-app-only-role`). */
+    roleArn: string;
+    /** Session name recorded in CloudTrail (often `session-${userId}-${Date.now()}`). */
+    roleSessionName: string;
+    /**
+     * Credential lifetime in seconds.
+     * @defaultValue 900
+     */
+    durationSeconds?: number;
+    /**
+     * STS SigV4 signing region.
+     * @defaultValue us-east-1
+     */
+    region?: string;
+    /**
+     * STS endpoint URL.
+     * @defaultValue https://sts.amazonaws.com/
+     */
+    endpoint?: string;
+}
+/**
+ * Temporary credentials returned by STS `AssumeRole`.
+ *
+ * @remarks
+ * Field names match the STS XML response / `@aws-sdk/client-sts` `Credentials` shape so browser
+ * apps can pass them straight into `@aws-sdk/client-s3` (`AccessKeyId` → `accessKeyId`, etc.).
+ */
+export interface StsCredentials {
+    AccessKeyId?: string;
+    SecretAccessKey?: string;
+    SessionToken?: string;
+    Expiration?: Date;
+}
+/**
+ * Call STS `AssumeRole` via SigV4-signed `fetch` (aws4fetch) and return temporary credentials.
+ *
+ * Port of winecode / airlec browser-upload credential issuance — no AWS SDK. The consuming app
+ * supplies `roleArn` and `roleSessionName`; the kit only performs the signed STS request and XML parse.
+ *
+ * @param options - Caller AWS keys plus assume-role parameters.
+ * @returns Temporary credentials for browser or edge PutObject / GetObject.
+ * @throws Error When the STS response is not OK.
+ * @example
+ * ```ts
+ * const credentials = await getTemporaryCredentials({
+ *   accessKeyId: env.AWS_ACCESS_KEY_ID,
+ *   secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+ *   roleArn: 'arn:aws:iam::123:role/s3-put-app-only-role',
+ *   roleSessionName: `session-${userId}-${Date.now()}`,
+ * });
+ * ```
+ */
+export declare function getTemporaryCredentials(options: GetTemporaryCredentialsOptions): Promise<StsCredentials>;

package/dist/aws/sts.js

@@ -0,0 +1,66 @@
+import { AwsClient } from 'aws4fetch';
+/** STS SigV4 signing region for the global endpoint (`sts.amazonaws.com`). */
+const DEFAULT_STS_REGION = 'us-east-1';
+/** winecode / airlec default — 15 minutes. */
+const DEFAULT_DURATION_SECONDS = 900;
+const STS_API_VERSION = '2011-06-15';
+/** Global STS endpoint (unchanged from winecode AwsService). */
+const DEFAULT_STS_ENDPOINT = 'https://sts.amazonaws.com/';
+/**
+ * Call STS `AssumeRole` via SigV4-signed `fetch` (aws4fetch) and return temporary credentials.
+ *
+ * Port of winecode / airlec browser-upload credential issuance — no AWS SDK. The consuming app
+ * supplies `roleArn` and `roleSessionName`; the kit only performs the signed STS request and XML parse.
+ *
+ * @param options - Caller AWS keys plus assume-role parameters.
+ * @returns Temporary credentials for browser or edge PutObject / GetObject.
+ * @throws Error When the STS response is not OK.
+ * @example
+ * ```ts
+ * const credentials = await getTemporaryCredentials({
+ *   accessKeyId: env.AWS_ACCESS_KEY_ID,
+ *   secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+ *   roleArn: 'arn:aws:iam::123:role/s3-put-app-only-role',
+ *   roleSessionName: `session-${userId}-${Date.now()}`,
+ * });
+ * ```
+ */
+export async function getTemporaryCredentials(options) {
+    const region = options.region ?? DEFAULT_STS_REGION;
+    const durationSeconds = options.durationSeconds ?? DEFAULT_DURATION_SECONDS;
+    const endpoint = options.endpoint ?? DEFAULT_STS_ENDPOINT;
+    const params = new URLSearchParams({
+        Action: 'AssumeRole',
+        Version: STS_API_VERSION,
+        RoleArn: options.roleArn,
+        RoleSessionName: options.roleSessionName,
+        DurationSeconds: String(durationSeconds),
+    });
+    const aws = new AwsClient({
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey,
+        sessionToken: options.sessionToken,
+        region,
+        service: 'sts',
+    });
+    const response = await aws.fetch(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: params.toString(),
+    });
+    const xml = await response.text();
+    if (!response.ok) {
+        throw new Error(`STS AssumeRole failed: ${response.status} ${xml}`);
+    }
+    const pick = (tag) => {
+        const m = new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml);
+        return m ? m[1] : undefined;
+    };
+    const expiration = pick('Expiration');
+    return {
+        AccessKeyId: pick('AccessKeyId'),
+        SecretAccessKey: pick('SecretAccessKey'),
+        SessionToken: pick('SessionToken'),
+        Expiration: expiration ? new Date(expiration) : undefined,
+    };
+}

package/dist/index.d.ts

@@ -59,6 +59,8 @@ export type { AiGatewayConfig, AiGatewayProvider, AiGatewayBinding, AiGateway, A
 export { getAuthenticationSecret } from './aws/secrets-manager.js';
 export type { AwsSecretsOptions } from './aws/secrets-manager.js';
 export { getCloudFrontSignedUrl } from './aws/cloudfront.js';
+export { getTemporaryCredentials } from './aws/sts.js';
+export type { GetTemporaryCredentialsOptions, StsCredentials } from './aws/sts.js';
 export type { DecodedIdToken, FirebaseVerifier } from './firebase/firebase-verifier.js';
 export { JoseFirebaseVerifier, SECURETOKEN_JWK_URL } from './firebase/jose-firebase-verifier.js';
 export { IdentityToolkit } from './firebase/identity-toolkit.js';

package/dist/index.js

@@ -47,6 +47,7 @@ export { createAiGatewayProvider } from './ai/gateway.js';
 // aws
 export { getAuthenticationSecret } from './aws/secrets-manager.js';
 export { getCloudFrontSignedUrl } from './aws/cloudfront.js';
+export { getTemporaryCredentials } from './aws/sts.js';
 export { JoseFirebaseVerifier, SECURETOKEN_JWK_URL } from './firebase/jose-firebase-verifier.js';
 export { IdentityToolkit } from './firebase/identity-toolkit.js';
 export { createRemoteFirebaseVerifier, createServiceAccountVerifier } from './firebase/remote-verifier.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "private": false,
   "publishConfig": {
     "access": "public"