--- name: fresh-auth description: This skill should be used when the user asks to access secured work data through "office", "email", "calendar", "microsoft graph", or "notion" using auth.freshhub.ai and the Freshwater secure auth proxy. --- # Fresh Auth Workspace CLI Use this skill as the single entry point for secure, identity-aware access to Microsoft 365 (Graph) and Notion. ## Use this skill for - Drive operations, OneDrive file access, and share links through `office-cli`. - Outlook inbox, search, send, and reply actions through `office-cli`. - Calendar lookup and scheduling visibility through `office-cli`. - People lookups through `office-cli`. - Notion database search, query, page read/write, and markdown conversion through `notion-query`. - Any request that mixes Office and Notion data in one workflow. ## Security model - Use the Auth Service Proxy at `https://auth.freshhub.ai` for Microsoft Graph and Notion actions. - Use agent-session grants and OAuth approvals, never raw provider tokens. - Keep `~/.config/fresh-auth/agent-session` at secure mode (600). - Legacy `~/.config/office-cli/agent-session` is still read for compatibility. - Store secrets in environment variables. - Use `OPENROUTER_API_KEY` for Office PDF/image conversion. - Use `AUTH_SERVICE_URL` only when overriding the default proxy endpoint. ## Runtime prerequisites - Install Node.js (18+) for `scripts/office-cli.js` and `scripts/notion-query.js`. - Run commands from this skill folder or export explicit paths. ```bash # Resolve skill location for common installers export FRESH_AUTH_DIR="${HOME}/.agents/skills/fresh-auth" [ -d "$FRESH_AUTH_DIR" ] || export FRESH_AUTH_DIR="${HOME}/.codex/skills/fresh-auth" export OFFICE_CLI="${FRESH_AUTH_DIR}/scripts/office-cli.js" export NOTION_CLI="${FRESH_AUTH_DIR}/scripts/notion-query.js" export AUTH_SERVICE_URL="https://auth.freshhub.ai" # Quick command discovery [ -f "$OFFICE_CLI" ] && node "$OFFICE_CLI" status [ -f "$NOTION_CLI" ] && node "$NOTION_CLI" status ``` ## Bundled scripts - `scripts/office-cli.js` for Microsoft Graph-backed Drive, Mail, Calendar, and People actions. - `scripts/notion-query.js` for Notion read/write workflows through auth service proxy. ## Office + Graph: canonical flow Follow this flow when granting access for Graph-backed tools. ```bash # Register and create grants node "$OFFICE_CLI" login node "$OFFICE_CLI" request drive node "$OFFICE_CLI" request mail node "$OFFICE_CLI" request cal node "$NOTION_CLI" request # Verify active grants node "$OFFICE_CLI" status node "$NOTION_CLI" status ``` ### Agent-assisted verification handoff When the agent runs `login` or `request`, the CLI may print a verification URL and code for human approval. 1. Agent runs the auth command and captures the exact verification output. 2. Agent sends the verification URL and code to the user (do not paraphrase). 3. Prefer sharing the prefilled URL format: `https://auth.freshhub.ai/agent/verify?code=` 4. User opens the URL, confirms the code, clicks `Verify Code`, then manually clicks `Approve` on the next screen. 5. Agent waits for approval polling to complete, then continues with the requested task. If approval fails, repeat the flow and confirm the user is signed into the intended Fresh Auth account before entering the code. ## Command map: Office CLI ## Drive / Graph storage ```bash node "$OFFICE_CLI" drive list node "$OFFICE_CLI" drive list "/Documents" node "$OFFICE_CLI" drive search "Quarterly report" node "$OFFICE_CLI" drive download out.docx node "$OFFICE_CLI" drive content node "$OFFICE_CLI" drive convert --output=notes.md node "$OFFICE_CLI" drive share --type edit node "$OFFICE_CLI" drive share --anyone node "$OFFICE_CLI" drive permissions node "$OFFICE_CLI" drive unshare ``` ## Mail / Email ```bash node "$OFFICE_CLI" mail inbox node "$OFFICE_CLI" mail inbox --count 50 node "$OFFICE_CLI" mail unread node "$OFFICE_CLI" mail search "team update" node "$OFFICE_CLI" mail read node "$OFFICE_CLI" mail send --to "teammate@example.com" --subject "Brief" --body "Thanks for the update" node "$OFFICE_CLI" mail send --to "brad" --subject "Quick check" --body "Approved" --yes node "$OFFICE_CLI" mail reply --body "Got it." node "$OFFICE_CLI" mail reply-all --body "Thanks everyone." ``` ## Calendar ```bash node "$OFFICE_CLI" cal today node "$OFFICE_CLI" cal tomorrow node "$OFFICE_CLI" cal events --days 14 node "$OFFICE_CLI" cal events --full ``` ## People lookup (Graph contact helper) ```bash node "$OFFICE_CLI" people "brad" node "$OFFICE_CLI" people "brad" --verbose ``` ## Notion command map ```bash node "$NOTION_CLI" login node "$NOTION_CLI" request node "$NOTION_CLI" status node "$NOTION_CLI" me node "$NOTION_CLI" find-db "my database" node "$NOTION_CLI" search "my database" node "$NOTION_CLI" get-db node "$NOTION_CLI" query-db node "$NOTION_CLI" get-page node "$NOTION_CLI" get-markdown node "$NOTION_CLI" create "Title" -p "Status=In progress" -p "Priority=High" node "$NOTION_CLI" update -p "Status=Done" node "$NOTION_CLI" set-body - node "$NOTION_CLI" append-body - ``` Use `find-db` first when the database ID is unknown. It returns database `id`, `title`, and `url` so the ID can be copied directly into `get-db`, `query-db`, or `create`. ## Notion backlog helper ```bash # Optional: enable shortcuts for a specific Notion backlog database export NOTION_BACKLOG_DB_ID="" node "$NOTION_CLI" backlog node "$NOTION_CLI" backlog "In Progress" node "$NOTION_CLI" create-backlog "New task" ``` ## Multi-tool patterns - Run `people` first, then `mail send --to ` for safer identity resolution. - Pull a Notion task with `search` or `query-db`, then append context with `append-body`. - Convert a meeting PDF in Drive to markdown with `drive convert`, then store notes in Notion via `append-body`. ## Error handling - `no_agent_session`: run `node "$OFFICE_CLI" login`. - `no_grant`: run `node "$OFFICE_CLI" request `. - `token expired`: run `node "$OFFICE_CLI" status` and follow the returned re-authorisation URL. - `no agent session` (Notion): run `node "$NOTION_CLI" login`. - `no grant` (Notion): run `node "$NOTION_CLI" request`. - `NOTION_BACKLOG_DB_ID` missing: set variable or call generic `query-db`/`create` commands instead of backlog shortcuts. - Microsoft account not linked: follow the URL output by Graph proxy responses. - Notion account not linked: follow the Notion connect URL output by the CLI. ## Public publication checks - Keep proxy URL configurable by `AUTH_SERVICE_URL`. - Do not embed API keys or session IDs in skill outputs. - Keep all commands pointed at `https://auth.freshhub.ai` by default. - Include both CLIs under this skill's `scripts/` folder for self-contained installation. - Mention both Microsoft 365 and Notion capabilities in onboarding docs because this is a unified user-facing access path.