feat(cedar-hitl): get-pending + get-policies + link-slack-user handlers

Lands the three read/discovery handlers Chunk 6 (CLI) needs to power
``bgagent pending``, ``bgagent policies list/show``, and
``bgagent notifications configure slack``. Completes §15.2 tasks
14, 15, and 25 (handler side).

Handlers
--------

``get-pending.ts`` (§7.7 — GET /v1/pending)
  - Queries ``user_id-status-index`` GSI on TaskApprovalsTable with
    ``user_id = :caller AND status = :pending``. Without the GSI
    this would be a full-table Scan per call — under
    ``watch -n1 bgagent pending`` that exhausts burst capacity for
    the whole fleet (§10.1 finding aws-samples#8).
  - Response maps each row to ``PendingApprovalSummary`` with a
    derived ``expires_at = created_at + timeout_s`` so the CLI can
    render time-to-timeout without doing arithmetic on ISO strings.
  - Severity coerced to ``medium`` on unknown values so GSI writes
    that drift from the enum don't break the list response.
  - Rate-limited 10/min/user (synthetic row on the same table,
    namespaced ``RATE#<user>#PENDING`` so it does not collide with
    the approve/deny counter).

``get-policies.ts`` (§7.6 — GET /v1/repos/{repo_id}/policies)
  - Combines ``BUILTIN_HARD_DENY_POLICIES`` + ``BUILTIN_SOFT_DENY_POLICIES``
    with the repo's ``cedar_policies`` blueprint override. Runs the
    combined text through ``parseRules`` and returns
    ``{hard[], soft[]}`` rule summaries.
  - 5-minute per-repo in-Lambda cache; cold starts throw it away.
    ``_resetCacheForTests`` exposed for unit-test isolation.
  - Repo ID is URL-decoded from the path (``owner%2Frepo`` common in
    CLI UX).
  - Rate-limited 30/min/user.
  - Blueprint load failure falls back to built-ins with a WARN log;
    invalid blueprint cedar text returns 503 ``SERVICE_UNAVAILABLE``
    rather than a misleading empty list.

``link-slack-user.ts`` (§11.2 finding aws-samples#4 — POST /v1/notifications/slack/link)
  - Writes to SlackUserMappingTable with
    ``ConditionExpression: attribute_not_exists(slack_user_id)``. This
    guard is the entire admission control the §11.2 design hinges on:
    even a compromised Slack admin cannot overwrite an existing
    mapping.
  - Validates ``slack_user_id`` shape (letters, digits, underscores,
    2–40 chars) so junk rows cannot land.
  - Conflict surface is 409 ``REQUEST_ALREADY_DECIDED`` — reused
    error code (the payload message directs the user to unlink via
    support).
  - Slack link_token end-to-end validation against Slack OAuth is
    deferred — v1 accepts the token on trust from the Cognito-authed
    caller; it is persisted in CloudWatch for audit.

Supporting primitives
---------------------

``shared/builtin-policies.ts`` — mirrors ``agent/policies/hard_deny.cedar``
and ``agent/policies/soft_deny.cedar`` as TypeScript string constants.
Embedded rather than read from disk because Lambda's esbuild bundler
does not copy non-TS assets by default and a dedicated bundling hook
is more code than the embed. A drift test
(``builtin-policies.test.ts``) asserts byte-equality with the agent
files so any change on one side without the other flips red at build
time.

``shared/cedar-policy.ts`` — ``parseRules`` now skips the unannotated
``base_permit`` entry (both tiers need it as a Cedar catch-all; it
is not a user-facing rule so it stays out of ParsedRule[]). This
matches the agent-side ``_parse_policy_annotations`` behaviour.

Tests: +37 total.
  - get-pending (8): 401 on missing auth, 429 on rate limit, empty
    result, GSI query shape, row → PendingApprovalSummary with
    derived expires_at, severity fallback, missing timeout → expires_at
    falls back to created_at, 500 on DDB error.
  - get-policies (11): 401/400 validation, built-in rules listed on
    empty repo, URL-decoded repo path, custom blueprint rule lands
    in soft, per-repo cache across calls, 429 rate limit, 503 on
    invalid blueprint cedar, fallback on load failure, hard rules
    omit severity / approval_timeout_s, soft rules carry them.
  - link-slack-user (8): 401/400 validation, shape check, 201 on
    success, 409 on overwrite attempt, 500 on unknown DDB error,
    whitespace trim on slack_user_id, ConditionExpression verified.
  - builtin-policies (4): drift byte-equality with both agent files,
    parseRules round-trip for hard/soft rule IDs.
  - cedar-policy (updated): ``base_permit`` is skipped from
    ParsedRule[] rather than rejected.

Stack wiring (task-api.ts routes, agent.ts layer attachment,
CreateTaskFn extension, orchestrator + reconciler + fanout) lands in
the next commit.

Author: bgagent

cdk/src/handlers/get-pending.ts

@@ -0,0 +1,174 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient, QueryCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
+import { ulid } from 'ulid';
+import { extractUserId } from './shared/gateway';
+import { logger } from './shared/logger';
+import { ErrorCode, errorResponse, successResponse } from './shared/response';
+import type { GetPendingResponse, PendingApprovalSummary } from './shared/types';
+
+const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
+const TASK_APPROVALS_TABLE_NAME = process.env.TASK_APPROVALS_TABLE_NAME;
+if (!TASK_APPROVALS_TABLE_NAME) {
+  throw new Error('get-pending handler requires TASK_APPROVALS_TABLE_NAME env var');
+}
+const USER_STATUS_INDEX_NAME = process.env.USER_STATUS_INDEX_NAME ?? 'user_id-status-index';
+const PENDING_RATE_LIMIT_PER_MINUTE = Number(process.env.PENDING_RATE_LIMIT_PER_MINUTE ?? '10');
+const PENDING_LIST_LIMIT = 100;
+
+/**
+ * GET /v1/pending — List pending approvals owned by the caller (§7.7).
+ *
+ * Backed by the `user_id-status-index` GSI on `TaskApprovalsTable`.
+ * Without the GSI a Scan would touch every approval row on every
+ * `watch -n1 bgagent pending` call and exhaust DDB burst capacity for
+ * the whole fleet (§10.1 finding #8).
+ *
+ * Rate-limited 10/min/user to belt-and-suspenders the GSI — runaway
+ * polling from a single user is capped before it touches the GSI at
+ * all.
+ *
+ * Response contains a `pending[]` of summaries, each with
+ * `expires_at` derived from `created_at + timeout_s` so the CLI can
+ * render time-to-timeout without the user doing the math.
+ */
+export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {
+  const requestId = ulid();
+
+  try {
+    const userId = extractUserId(event);
+    if (!userId) {
+      return errorResponse(401, ErrorCode.UNAUTHORIZED, 'Missing or invalid authentication.', requestId);
+    }
+
+    const nowEpoch = Math.floor(Date.now() / 1000);
+
+    // Per-user per-minute rate limit. Uses a synthetic row on the
+    // approvals table with `RATE#<user_id>#PENDING` PK to avoid
+    // colliding with the approve/deny counter (same table but
+    // different PK namespace).
+    const minuteBucket = formatMinuteBucket(new Date());
+    try {
+      await ddb.send(new UpdateCommand({
+        TableName: TASK_APPROVALS_TABLE_NAME,
+        Key: {
+          task_id: `RATE#${userId}#PENDING`,
+          request_id: `MINUTE#${minuteBucket}`,
+        },
+        UpdateExpression: 'ADD #count :one SET #ttl = :ttl',
+        ConditionExpression: 'attribute_not_exists(#count) OR #count < :max',
+        ExpressionAttributeNames: {
+          '#count': 'count',
+          '#ttl': 'ttl',
+        },
+        ExpressionAttributeValues: {
+          ':one': 1,
+          ':max': PENDING_RATE_LIMIT_PER_MINUTE,
+          ':ttl': nowEpoch + 120,
+        },
+      }));
+    } catch (err: unknown) {
+      const name = (err as { name?: string })?.name;
+      if (name === 'ConditionalCheckFailedException') {
+        return errorResponse(
+          429,
+          ErrorCode.RATE_LIMIT_EXCEEDED,
+          `Rate limit exceeded: at most ${PENDING_RATE_LIMIT_PER_MINUTE} pending-list queries per minute.`,
+          requestId,
+        );
+      }
+      throw err;
+    }
+
+    const result = await ddb.send(new QueryCommand({
+      TableName: TASK_APPROVALS_TABLE_NAME,
+      IndexName: USER_STATUS_INDEX_NAME,
+      KeyConditionExpression: 'user_id = :user AND #status = :pending',
+      ExpressionAttributeNames: { '#status': 'status' },
+      ExpressionAttributeValues: {
+        ':user': userId,
+        ':pending': 'PENDING',
+      },
+      Limit: PENDING_LIST_LIMIT,
+    }));
+
+    const items = (result.Items ?? []) as ReadonlyArray<Record<string, unknown>>;
+    const pending: PendingApprovalSummary[] = items.map((row) => {
+      const created_at = String(row.created_at ?? '');
+      const timeout_s = Number(row.timeout_s ?? 0);
+      const expires_at = computeExpiresAt(created_at, timeout_s);
+      return {
+        task_id: String(row.task_id ?? ''),
+        request_id: String(row.request_id ?? ''),
+        tool_name: String(row.tool_name ?? ''),
+        tool_input_preview: String(row.tool_input_preview ?? ''),
+        severity: coerceSeverity(row.severity),
+        reason: String(row.reason ?? ''),
+        created_at,
+        timeout_s,
+        expires_at,
+      };
+    });
+
+    logger.info('Pending approvals listed', {
+      user_id: userId,
+      count: pending.length,
+      request_id: requestId,
+    });
+
+    const response: GetPendingResponse = { pending };
+    return successResponse(200, response, requestId);
+  } catch (err) {
+    logger.error('Failed to list pending approvals', {
+      error: err instanceof Error ? err.message : String(err),
+      request_id: requestId,
+    });
+    return errorResponse(500, ErrorCode.INTERNAL_ERROR, 'Internal server error.', requestId);
+  }
+}
+
+function coerceSeverity(value: unknown): 'low' | 'medium' | 'high' {
+  if (value === 'low' || value === 'medium' || value === 'high') {
+    return value;
+  }
+  return 'medium';
+}
+
+function computeExpiresAt(createdAt: string, timeoutS: number): string {
+  if (!createdAt || !Number.isFinite(timeoutS) || timeoutS <= 0) {
+    return createdAt;
+  }
+  const created = Date.parse(createdAt);
+  if (Number.isNaN(created)) {
+    return createdAt;
+  }
+  return new Date(created + timeoutS * 1000).toISOString();
+}
+
+function formatMinuteBucket(date: Date): string {
+  const y = date.getUTCFullYear().toString().padStart(4, '0');
+  const m = (date.getUTCMonth() + 1).toString().padStart(2, '0');
+  const d = date.getUTCDate().toString().padStart(2, '0');
+  const h = date.getUTCHours().toString().padStart(2, '0');
+  const mi = date.getUTCMinutes().toString().padStart(2, '0');
+  return `${y}${m}${d}${h}${mi}`;
+}

cdk/src/handlers/get-policies.ts

@@ -0,0 +1,214 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
+import { ulid } from 'ulid';
+import {
+  BUILTIN_HARD_DENY_POLICIES,
+  BUILTIN_SOFT_DENY_POLICIES,
+} from './shared/builtin-policies';
+import { CedarPolicyParseError, concatPolicies, parseRules } from './shared/cedar-policy';
+import { extractUserId } from './shared/gateway';
+import { logger } from './shared/logger';
+import { loadRepoConfig } from './shared/repo-config';
+import { ErrorCode, errorResponse, successResponse } from './shared/response';
+import type { GetPoliciesResponse, PolicyRuleSummary } from './shared/types';
+
+const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
+const TASK_APPROVALS_TABLE_NAME = process.env.TASK_APPROVALS_TABLE_NAME;
+const POLICIES_RATE_LIMIT_PER_MINUTE = Number(process.env.POLICIES_RATE_LIMIT_PER_MINUTE ?? '30');
+
+// In-Lambda cache keyed by repo; 5 minutes. Keeps repeated `bgagent
+// policies list` calls snappy without hitting DDB + re-parsing the
+// policy set every time. Cold starts throw the cache away.
+const CACHE_TTL_MS = 5 * 60 * 1000;
+interface CacheEntry {
+  readonly response: GetPoliciesResponse;
+  readonly expiresAt: number;
+}
+const cache = new Map<string, CacheEntry>();
+
+/**
+ * GET /v1/repos/{repo_id}/policies — List Cedar rules for a repo (§7.6).
+ *
+ * Response combines the built-in hard/soft policy sets with any
+ * `cedar_policies` the repo's blueprint has registered. Each rule is
+ * rendered as a `{rule_id, category, severity?, approval_timeout_s?,
+ * summary}` envelope.
+ *
+ * Rate-limited 30/min/user — generous for UX (`bgagent policies list`
+ * is an interactive lookup) but bounded so a runaway script cannot
+ * hammer the shared Cedar parser.
+ *
+ * `repo_id` is URL-decoded from the path parameter (`owner%2Frepo`
+ * encoding is common in CLI UX).
+ */
+export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {
+  const requestId = ulid();
+
+  try {
+    const userId = extractUserId(event);
+    if (!userId) {
+      return errorResponse(401, ErrorCode.UNAUTHORIZED, 'Missing or invalid authentication.', requestId);
+    }
+
+    const rawRepoId = event.pathParameters?.repo_id;
+    if (!rawRepoId) {
+      return errorResponse(400, ErrorCode.VALIDATION_ERROR, 'Missing repo_id path parameter.', requestId);
+    }
+    const repoId = decodeURIComponent(rawRepoId);
+
+    // Rate-limit. Uses a synthetic row on the approvals table keyed on
+    // `RATE#<user_id>#POLICIES` to avoid colliding with the approve /
+    // pending counters.
+    if (TASK_APPROVALS_TABLE_NAME) {
+      const nowEpoch = Math.floor(Date.now() / 1000);
+      const minuteBucket = formatMinuteBucket(new Date());
+      try {
+        await ddb.send(new UpdateCommand({
+          TableName: TASK_APPROVALS_TABLE_NAME,
+          Key: {
+            task_id: `RATE#${userId}#POLICIES`,
+            request_id: `MINUTE#${minuteBucket}`,
+          },
+          UpdateExpression: 'ADD #count :one SET #ttl = :ttl',
+          ConditionExpression: 'attribute_not_exists(#count) OR #count < :max',
+          ExpressionAttributeNames: { '#count': 'count', '#ttl': 'ttl' },
+          ExpressionAttributeValues: {
+            ':one': 1,
+            ':max': POLICIES_RATE_LIMIT_PER_MINUTE,
+            ':ttl': nowEpoch + 120,
+          },
+        }));
+      } catch (err: unknown) {
+        const name = (err as { name?: string })?.name;
+        if (name === 'ConditionalCheckFailedException') {
+          return errorResponse(
+            429,
+            ErrorCode.RATE_LIMIT_EXCEEDED,
+            `Rate limit exceeded: at most ${POLICIES_RATE_LIMIT_PER_MINUTE} policy-list queries per minute.`,
+            requestId,
+          );
+        }
+        throw err;
+      }
+    }
+
+    // Cache check. Per-repo TTL of 5 min (IMPL-note — does not include
+    // user_id because the policy set is not user-specific).
+    const cached = cache.get(repoId);
+    if (cached && cached.expiresAt > Date.now()) {
+      return successResponse(200, cached.response, requestId);
+    }
+
+    // Load blueprint config (optional — repos without custom policies
+    // still get the built-in set).
+    let blueprintCedarPolicies: readonly string[] = [];
+    try {
+      const repoConfig = await loadRepoConfig(repoId);
+      if (repoConfig) {
+        blueprintCedarPolicies = repoConfig.cedar_policies ?? [];
+      }
+    } catch (configErr) {
+      logger.warn('Could not load repo config for policies endpoint — continuing with built-ins', {
+        repo_id: repoId,
+        error: configErr instanceof Error ? configErr.message : String(configErr),
+      });
+    }
+
+    const blueprintText = blueprintCedarPolicies.join('\n');
+    const hardText = BUILTIN_HARD_DENY_POLICIES;
+    const softText = concatPolicies(BUILTIN_SOFT_DENY_POLICIES, blueprintText);
+
+    let hardRules;
+    let softRules;
+    try {
+      hardRules = parseRules(hardText);
+      softRules = parseRules(softText);
+    } catch (err) {
+      if (err instanceof CedarPolicyParseError) {
+        logger.error('Cedar parse failure for repo policies', {
+          repo_id: repoId,
+          message: err.message,
+        });
+        return errorResponse(
+          503,
+          ErrorCode.SERVICE_UNAVAILABLE,
+          'Policy set for this repo is currently invalid.',
+          requestId,
+        );
+      }
+      throw err;
+    }
+
+    const response: GetPoliciesResponse = {
+      repo_id: repoId,
+      policies: {
+        hard: hardRules
+          .filter((r) => r.tier === 'hard')
+          .map(toSummary),
+        soft: softRules
+          .filter((r) => r.tier === 'soft')
+          .map(toSummary),
+      },
+    };
+
+    cache.set(repoId, {
+      response,
+      expiresAt: Date.now() + CACHE_TTL_MS,
+    });
+
+    return successResponse(200, response, requestId);
+  } catch (err) {
+    logger.error('Failed to list policies', {
+      error: err instanceof Error ? err.message : String(err),
+      request_id: requestId,
+    });
+    return errorResponse(500, ErrorCode.INTERNAL_ERROR, 'Internal server error.', requestId);
+  }
+}
+
+function toSummary(rule: ReturnType<typeof parseRules>[number]): PolicyRuleSummary {
+  const out: {
+    -readonly [K in keyof PolicyRuleSummary]?: PolicyRuleSummary[K];
+  } = {
+    rule_id: rule.rule_id,
+    summary: rule.summary,
+  };
+  if (rule.category) out.category = rule.category;
+  if (rule.severity) out.severity = rule.severity;
+  if (rule.approval_timeout_s) out.approval_timeout_s = rule.approval_timeout_s;
+  return out as PolicyRuleSummary;
+}
+
+function formatMinuteBucket(date: Date): string {
+  const y = date.getUTCFullYear().toString().padStart(4, '0');
+  const m = (date.getUTCMonth() + 1).toString().padStart(2, '0');
+  const d = date.getUTCDate().toString().padStart(2, '0');
+  const h = date.getUTCHours().toString().padStart(2, '0');
+  const mi = date.getUTCMinutes().toString().padStart(2, '0');
+  return `${y}${m}${d}${h}${mi}`;
+}
+
+/** Test-only cache reset — exposed for unit tests. */
+export function _resetCacheForTests(): void {
+  cache.clear();
+}