@meffecta/agent 0.0.1

package/scripts/mint-graph-token.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// One-time, local: mint the OAuth refresh token the agent uses to read a Microsoft
+// 365 mailbox through Microsoft Graph. Opens a browser consent flow via a loopback
+// redirect and prints the refresh token — store it as MSGRAPH_<NAME>_REFRESH_TOKEN.
+//
+// Delegated, never app-only. An app-only Mail.Read grant reaches EVERY mailbox in
+// the tenant and has to be fenced back in with an Exchange ApplicationAccessPolicy;
+// a delegated token can only ever reach the mailbox that signs in below. For a
+// mailbox in someone else's company that difference is the whole point.
+//
+// Prerequisites (once, in the target tenant — you must be able to register an app):
+//   1. Entra admin center → App registrations → New registration.
+//      - Supported account types: "Accounts in this organizational directory only".
+//      - Platform "Web", Redirect URI EXACTLY http://localhost:3014/
+//        Entra matches redirect URIs exactly — there is no random-loopback-port
+//        exemption as with Google, which is why the port here is pinned.
+//   2. Certificates & secrets → New client secret; copy the VALUE, not the id.
+//      The secret is what makes this a confidential client, whose refresh tokens
+//      live until revoked. Without one, Entra caps refresh tokens at 90 days and
+//      this breaks every quarter. Client secrets themselves expire (24 months max)
+//      — note the date somewhere you will see it.
+//   3. API permissions → Microsoft Graph → Delegated → Mail.Read AND Calendars.Read.
+//      Grant admin consent if the tenant requires it. (--no-calendar mints without
+//      Calendars.Read; the calendar is normally the more useful half, so it is on
+//      by default and dropping it later means a fresh consent round.)
+//   4. Note the Application (client) ID and the Directory (tenant) ID.
+//
+// Usage:
+//   node scripts/mint-graph-token.mjs --account MOXSEA --tenant <tenant-id> \
+//     --client-id <id> --client-secret <secret> [--no-calendar]
+//
+// Sign in as the mailbox the token is for when the browser opens — the everyday
+// account, NOT a tenant admin account. An Admin-* identity usually carries no
+// Exchange licence, so the consent succeeds and every later mail call returns 404
+// "mailbox is either inactive, soft-deleted, or is hosted on-premise". If the
+// browser is already signed in as the admin, use "Use another account" or a private
+// window. Scopes are read-only by construction: this mints no Mail.Send and no write
+// scope of any kind, so a token minted here cannot send, reply, or delete.
+
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { parseArgs } from "node:util";
+
+const { values: args } = parseArgs({
+  options: {
+    account: { type: "string" },
+    tenant: { type: "string" },
+    "client-id": { type: "string" },
+    "client-secret": { type: "string" },
+    "no-calendar": { type: "boolean", default: false },
+  },
+});
+
+// Entra's redirect URI must match the registration exactly, so this is fixed.
+const PORT = 3014;
+const REDIRECT_URI = `http://localhost:${PORT}/`;
+
+const accountName = args.account?.toUpperCase();
+if (!accountName || !/^[A-Z0-9]+$/.test(accountName)) {
+  console.error(
+    "--account is required and must be a single alphanumeric word (it becomes MSGRAPH_<NAME>_REFRESH_TOKEN)",
+  );
+  process.exit(1);
+}
+const tokenVar = `MSGRAPH_${accountName}_REFRESH_TOKEN`;
+
+const tenant = args.tenant ?? process.env.MSGRAPH_TENANT_ID;
+const clientId = args["client-id"] ?? process.env.MSGRAPH_CLIENT_ID;
+const clientSecret = args["client-secret"] ?? process.env.MSGRAPH_CLIENT_SECRET;
+if (!tenant || !clientId || !clientSecret) {
+  console.error("usage: mint-graph-token.mjs --account <NAME> --tenant <id> --client-id <id> --client-secret <secret>");
+  process.exit(1);
+}
+
+const SCOPES = [
+  "offline_access",
+  "https://graph.microsoft.com/Mail.Read",
+  ...(args["no-calendar"] ? [] : ["https://graph.microsoft.com/Calendars.Read"]),
+];
+
+// PKCE: required for public clients, harmless here, and it keeps the authorization
+// code useless to anything that intercepts the loopback redirect.
+const verifier = randomBytes(32).toString("base64url");
+const challenge = createHash("sha256").update(verifier).digest("base64url");
+
+const server = createServer();
+await new Promise((resolve, reject) => {
+  server.once("error", (err) =>
+    reject(
+      err.code === "EADDRINUSE"
+        ? new Error(`port ${PORT} is busy — free it; the redirect URI is registered against that exact port`)
+        : err,
+    ),
+  );
+  server.listen(PORT, "127.0.0.1", resolve);
+});
+
+const authUrl = new URL(`https://login.microsoftonline.com/${tenant}/oauth2/v2.0/authorize`);
+authUrl.search = new URLSearchParams({
+  client_id: clientId,
+  response_type: "code",
+  redirect_uri: REDIRECT_URI,
+  response_mode: "query",
+  scope: SCOPES.join(" "),
+  code_challenge: challenge,
+  code_challenge_method: "S256",
+  // Force account choice: signing in as the wrong identity is the easy mistake here.
+  prompt: "select_account",
+}).toString();
+
+console.error(`Open this URL and sign in as the ${accountName} mailbox (read-only scopes: ${SCOPES.join(", ")}).`);
+console.error("Use the everyday account, not a tenant admin account — admin identities have no mailbox.\n");
+console.error(authUrl.toString());
+console.error("\nWaiting for the redirect...");
+
+const code = await new Promise((resolve, reject) => {
+  server.on("request", (req, res) => {
+    const url = new URL(req.url, REDIRECT_URI);
+    const err = url.searchParams.get("error");
+    const description = url.searchParams.get("error_description");
+    const c = url.searchParams.get("code");
+    res.writeHead(200, { "content-type": "text/html" });
+    res.end(err ? `<h3>Failed: ${err}</h3><p>${description ?? ""}</p>` : "<h3>Done — you can close this tab.</h3>");
+    if (err) reject(new Error(`${err}: ${description ?? ""}`));
+    else if (c) resolve(c);
+  });
+});
+server.close();
+
+const res = await fetch(`https://login.microsoftonline.com/${tenant}/oauth2/v2.0/token`, {
+  method: "POST",
+  headers: { "content-type": "application/x-www-form-urlencoded" },
+  body: new URLSearchParams({
+    client_id: clientId,
+    client_secret: clientSecret,
+    code,
+    grant_type: "authorization_code",
+    redirect_uri: REDIRECT_URI,
+    code_verifier: verifier,
+    scope: SCOPES.join(" "),
+  }),
+});
+const json = await res.json();
+if (!res.ok || !json.refresh_token) {
+  console.error(`token exchange failed (${res.status}): ${JSON.stringify(json.error_description ?? json)}`);
+  process.exit(1);
+}
+
+// Refresh token to stdout (pipe straight into gcloud), everything else to stderr.
+console.error(`\nRefresh token minted — it is ${tokenVar}. Store it without it touching your shell history:`);
+console.error(`  node scripts/mint-graph-token.mjs ... | gcloud secrets create ${tokenVar} --data-file=-\n`);
+console.log(json.refresh_token);

package/scripts/set-artifact-cleanup.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Stop a deployment's Artifact Registry filling up with engine images it will never use
+# again.
+#
+# The images there are a **cache**, not an archive: deploy.sh mirrors them from
+# ghcr.io/meffecta/agent because Cloud Run cannot pull from GHCR directly. GHCR keeps the
+# real copies, so anything deleted here comes back on the next `deploy.sh --tag <that one>`.
+# That is what makes an aggressive policy correct for this repo and wrong for a repo whose
+# images have nowhere else to come from.
+#
+# The policy (artifact-cleanup-policy.json, beside this script):
+#   keep-recent-versions  the newest 5 per image, always
+#   delete-untagged       superseded pushes — the previous :latest, mostly — after a day
+#   delete-superseded     anything at all, once it is 30 days old
+#
+# Keep rules win over delete rules in Artifact Registry, which is the safety property this
+# leans on: **the image the live revision pins must never be deleted.** A Cloud Run revision
+# pins a digest, and under scale-to-zero every cold start pulls it — so deleting the running
+# image does not merely block the next deploy, it takes the service down at the next wake-up.
+# The newest 5 covers the live one with four deploys of slack.
+#
+# Usage:
+#   scripts/set-artifact-cleanup.sh              # apply the policy; deletions are real
+#   scripts/set-artifact-cleanup.sh --observe    # apply it in Artifact Registry's own
+#                                                #   dry-run mode: it logs what it would
+#                                                #   delete and deletes nothing
+#   scripts/set-artifact-cleanup.sh --dry-run    # change nothing at all, just show
+#   scripts/set-artifact-cleanup.sh --off        # remove the policy
+#
+# Which deployment: ./deployment.env, or --config <file>. See deployment.env.example.
+
+. "$(dirname "${BASH_SOURCE[0]}")/lib/deployment.sh"
+
+POLICY_FILE="$(dirname "${BASH_SOURCE[0]}")/artifact-cleanup-policy.json"
+DRY_RUN=false
+OBSERVE=false
+REMOVE=false
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --config) CONFIG_FILE="${2:?--config needs a file}"; shift 2 ;;
+    --policy) POLICY_FILE="${2:?--policy needs a file}"; shift 2 ;;
+    --observe) OBSERVE=true; shift ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    --off) REMOVE=true; shift ;;
+    -h|--help) sed -n '3,33p' "$0"; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+require_gcloud
+resolve_deployment
+announce_target "Setting the image cleanup policy on ${ARTIFACT_REPO}"
+
+[ -f "${POLICY_FILE}" ] || { echo "Policy file not found: ${POLICY_FILE}" >&2; exit 1; }
+
+GC="gcloud --project=${PROJECT}"
+[ -n "${ACCOUNT:-}" ] && GC="${GC} --account=${ACCOUNT}"
+
+# gcloud prints the size only in its default layout, not as a --format key.
+SIZE_BEFORE=$(${GC} artifacts repositories describe "${ARTIFACT_REPO}" --location="${REGION}" 2>/dev/null |
+  sed -n 's/^Repository Size: //p' || echo "")
+[ -n "${SIZE_BEFORE}" ] && echo "   current size: ${SIZE_BEFORE}"
+
+if [ "${REMOVE}" = true ]; then
+  echo "🧹 Removing the cleanup policy — nothing will be deleted automatically any more."
+  if [ "${DRY_RUN}" = true ]; then
+    echo "   (dry run: nothing was changed)"
+    exit 0
+  fi
+  ${GC} artifacts repositories delete-cleanup-policies "${ARTIFACT_REPO}" --location="${REGION}" \
+    --policynames=keep-recent-versions,delete-untagged,delete-superseded
+  exit 0
+fi
+
+echo "🧹 Policy:"
+sed 's/^/   /' "${POLICY_FILE}"
+
+FLAGS=(--policy="${POLICY_FILE}")
+if [ "${OBSERVE}" = true ]; then
+  # Artifact Registry evaluates the policy and logs what it would remove, without removing
+  # it. The log filter is printed below — give it a few hours to run.
+  FLAGS+=(--dry-run)
+  echo "   mode: observe (Artifact Registry logs deletions instead of making them)"
+else
+  FLAGS+=(--no-dry-run)
+  echo "   mode: enforcing (deletions are real, and the images come back from GHCR if needed)"
+fi
+
+if [ "${DRY_RUN}" = true ]; then
+  echo "   (dry run: nothing was changed)"
+  exit 0
+fi
+
+${GC} artifacts repositories set-cleanup-policies "${ARTIFACT_REPO}" --location="${REGION}" "${FLAGS[@]}"
+
+echo ""
+echo "✅ Applied. Artifact Registry evaluates the policy on its own schedule, so the size"
+echo "   drops over the following hours rather than immediately."
+if [ "${OBSERVE}" = true ]; then
+  echo ""
+  echo "   Watch what it would delete:"
+  echo "     gcloud logging read 'resource.type=\"artifactregistry.googleapis.com/Repository\"" \
+    "AND jsonPayload.policyName!=\"\"' --project ${PROJECT} --limit 50"
+  echo "   Then re-run without --observe to let it act."
+fi

package/scripts/set-env.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Set plain (non-secret) environment variables on the deployment's Cloud Run service.
+# Several at once become one revision instead of one each.
+#
+# Anything sensitive belongs in scripts/set-secret.sh instead — values passed here are
+# visible in your shell history and in the service's configuration.
+#
+# Usage:
+#   scripts/set-env.sh GIT_REPO_URL=https://github.com/acme/agent-home.git
+#   scripts/set-env.sh GMAIL_ADDRESS=a@b.com TIMEZONE=Europe/Stockholm
+#   scripts/set-env.sh --unset SOME_OLD_VAR
+#
+#   --config <file>   use another deployment's config (default: ./deployment.env)
+
+. "$(dirname "${BASH_SOURCE[0]}")/lib/deployment.sh"
+
+PAIRS=()
+UNSET_KEYS=()
+DRY_RUN=false
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --config) CONFIG_FILE="${2:?--config needs a file}"; shift 2 ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    --unset) UNSET_KEYS+=("${2:?--unset needs a name}"); shift 2 ;;
+    -h|--help) sed -n '4,16p' "$0"; exit 0 ;;
+    -*) echo "Unknown argument: $1" >&2; exit 2 ;;
+    *)
+      case "$1" in
+        *=*) PAIRS+=("$1") ;;
+        *) echo "Expected NAME=VALUE, got '$1'" >&2; exit 2 ;;
+      esac
+      shift ;;
+  esac
+done
+
+if [ ${#PAIRS[@]} -eq 0 ] && [ ${#UNSET_KEYS[@]} -eq 0 ]; then
+  echo "Nothing to do: pass NAME=VALUE pairs, or --unset NAME." >&2
+  exit 2
+fi
+
+require_gcloud
+resolve_deployment
+announce_target "Updating environment on ${SERVICE}"
+
+ARGS=()
+if [ ${#PAIRS[@]} -gt 0 ]; then
+  # gcloud splits --update-env-vars on commas unless a custom delimiter is declared as
+  # ^delim^. Values here legitimately contain commas (a job list) and @ (an address), so
+  # pick a delimiter none of them uses rather than assuming.
+  DELIM=""
+  for candidate in ',' '|' '#' '~'; do
+    if ! printf '%s\n' "${PAIRS[@]}" | grep -qF "${candidate}"; then
+      DELIM="${candidate}"
+      break
+    fi
+  done
+  [ -n "${DELIM}" ] || { echo "Values use every candidate delimiter; set these one at a time." >&2; exit 1; }
+
+  JOINED=""
+  for pair in "${PAIRS[@]}"; do
+    [ -n "${JOINED}" ] && JOINED="${JOINED}${DELIM}"
+    JOINED="${JOINED}${pair}"
+    echo "   set ${pair%%=*}"
+  done
+  if [ "${DELIM}" = ',' ]; then
+    ARGS+=(--update-env-vars "${JOINED}")
+  else
+    ARGS+=(--update-env-vars "^${DELIM}^${JOINED}")
+  fi
+fi
+
+if [ ${#UNSET_KEYS[@]} -gt 0 ]; then
+  REMOVE=""
+  for key in "${UNSET_KEYS[@]}"; do
+    [ -n "${REMOVE}" ] && REMOVE="${REMOVE},"
+    REMOVE="${REMOVE}${key}"
+    echo "   unset ${key}"
+  done
+  ARGS+=(--remove-env-vars "${REMOVE}")
+fi
+
+echo ""
+if [ "${DRY_RUN}" = true ]; then
+  echo "(dry run: nothing was changed)"
+  exit 0
+fi
+gcloud run services update "${SERVICE}" --project "${PROJECT}" --region "${REGION}" \
+  "${ARGS[@]}" >/dev/null
+echo "✔ Updated (new revision rolling out)."

package/scripts/set-secret.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Put a secret in Secret Manager and bind it to the deployment's Cloud Run service.
+# Creates the secret on first use, adds a new version afterwards, and wires the service
+# to :latest — so re-running it rotates a value in one step.
+#
+# The value never appears in your shell history, in the process list, or on screen.
+#
+# Usage:
+#   scripts/set-secret.sh AGENT_WEBHOOK_SECRET --random   # generate one, 32 random bytes
+#   scripts/set-secret.sh GITHUB_TOKEN                    # prompt (hidden), or read stdin
+#   scripts/set-secret.sh GMAIL_REFRESH_TOKEN --from-file token.txt
+#   cat token.txt | scripts/set-secret.sh GMAIL_REFRESH_TOKEN
+#
+#   --config <file>   use another deployment's config (default: ./deployment.env)
+#   --no-bind         store the version only, leave the service untouched
+
+. "$(dirname "${BASH_SOURCE[0]}")/lib/deployment.sh"
+
+NAME=""
+RANDOM_VALUE=false
+FROM_FILE=""
+BIND=true
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --config) CONFIG_FILE="${2:?--config needs a file}"; shift 2 ;;
+    --random) RANDOM_VALUE=true; shift ;;
+    --from-file) FROM_FILE="${2:?--from-file needs a path}"; shift 2 ;;
+    --no-bind) BIND=false; shift ;;
+    -h|--help) sed -n '4,20p' "$0"; exit 0 ;;
+    -*) echo "Unknown argument: $1" >&2; exit 2 ;;
+    *) NAME="$1"; shift ;;
+  esac
+done
+
+[ -n "${NAME}" ] || { echo "Which secret? e.g. scripts/set-secret.sh GITHUB_TOKEN" >&2; exit 2; }
+case "${NAME}" in
+  [A-Z]*[A-Z0-9]|[A-Z]) ;;
+  *) echo "Secret names are UPPER_SNAKE_CASE: got '${NAME}'" >&2; exit 2 ;;
+esac
+
+require_gcloud
+resolve_deployment
+announce_target "Setting secret ${NAME}"
+
+# --- Collect the value without ever putting it on the command line ---
+VALUE_FILE=$(mktemp)
+trap 'rm -f "${VALUE_FILE}"' EXIT
+
+if [ "${RANDOM_VALUE}" = true ]; then
+  command -v openssl >/dev/null || { echo "openssl is required for --random." >&2; exit 1; }
+  openssl rand -hex 32 | tr -d '\n' >"${VALUE_FILE}"
+  echo "Generated a new 32-byte random value."
+elif [ -n "${FROM_FILE}" ]; then
+  [ -f "${FROM_FILE}" ] || { echo "No such file: ${FROM_FILE}" >&2; exit 1; }
+  tr -d '\n' <"${FROM_FILE}" >"${VALUE_FILE}"
+elif [ ! -t 0 ]; then
+  tr -d '\n' >"${VALUE_FILE}" # piped in
+else
+  printf 'Value for %s (input hidden): ' "${NAME}" >&2
+  IFS= read -rs TYPED
+  echo "" >&2
+  printf '%s' "${TYPED}" >"${VALUE_FILE}"
+  unset TYPED
+fi
+
+[ -s "${VALUE_FILE}" ] || { echo "Refusing to store an empty value for ${NAME}." >&2; exit 1; }
+
+if gcloud secrets describe "${NAME}" --project "${PROJECT}" >/dev/null 2>&1; then
+  gcloud secrets versions add "${NAME}" --project "${PROJECT}" --data-file="${VALUE_FILE}" >/dev/null
+  echo "✔ Added a new version of ${NAME}."
+else
+  gcloud secrets create "${NAME}" --project "${PROJECT}" --data-file="${VALUE_FILE}" \
+    --replication-policy=automatic >/dev/null
+  echo "✔ Created secret ${NAME}."
+fi
+
+if [ "${BIND}" = true ]; then
+  gcloud run services update "${SERVICE}" --project "${PROJECT}" --region "${REGION}" \
+    --update-secrets "${NAME}=${NAME}:latest" >/dev/null
+  echo "✔ Bound ${NAME} on ${SERVICE} (new revision rolling out)."
+else
+  echo "• Service untouched (--no-bind)."
+fi