Back to Details

fresh-auth

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fresh Auth Workspace CLI

Fresh Auth 工作区 CLI

Use this skill as the single entry point for secure, identity-aware access to Microsoft 365 (Graph) and Notion.
将此skill用作安全、基于身份的Microsoft 365（Graph）和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.
  • 通过
    office-cli
    进行驱动器操作、OneDrive文件访问和共享链接管理。
  • 通过
    office-cli
    执行Outlook收件箱查看、搜索、发送和回复操作。
  • 通过
    office-cli
    进行日历查询和日程可见性管理。
  • 通过
    office-cli
    进行人员查询。
  • 通过
    notion-query
    进行Notion数据库搜索、查询、页面读写和Markdown转换。
  • 任何在单个工作流中混合Office和Notion数据的请求。

Security model

安全模型

  • Use the Auth Service Proxy at 
    https://auth.freshhub.ai
    for Microsoft Graph actions.
  • Use 
    office-cli
    with agent-session grants, never raw OAuth tokens.
  • Keep 
    ~/.config/office-cli/agent-session
    at secure mode (600).
  • Store secrets in environment variables.
  • Use 
    NOTION_API_KEY
    for Notion API requests.
  • Use 
    OPENROUTER_API_KEY
    for Office PDF/image conversion.
  • Use 
    AUTH_SERVICE_URL
    only when overriding the default proxy endpoint.
  • 针对Microsoft Graph操作使用位于
    https://auth.freshhub.ai
    的认证服务代理。
  • 使用带有agent-session授权的
    office-cli
    ，绝不要使用原始OAuth令牌。
  • 将
    ~/.config/office-cli/agent-session
    设置为安全模式（600）。
  • 将密钥存储在环境变量中。
  • 针对Notion API请求使用
    NOTION_API_KEY
    。
  • 针对Office PDF/图片转换使用
    OPENROUTER_API_KEY
    。
  • 仅在覆盖默认代理端点时使用
    AUTH_SERVICE_URL
    。

Runtime prerequisites

运行时先决条件

  • Install Bun for 
    scripts/office-cli.ts
    .
  • Install 
    jq
    and 
    curl
    for 
    scripts/notion-query.sh
    .
  • Run commands from this skill folder or export explicit paths.
bash
undefined
  • 为
    scripts/office-cli.ts
    安装Bun。
  • 为
    scripts/notion-query.sh
    安装
    jq
    和
    curl
    。
  • 从此skill文件夹运行命令，或导出明确的路径。
bash
undefined

Resolve skill location for common installers

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.ts" export NOTION_CLI="${FRESH_AUTH_DIR}/scripts/notion-query.sh" export AUTH_SERVICE_URL="https://auth.freshhub.ai"
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.ts" export NOTION_CLI="${FRESH_AUTH_DIR}/scripts/notion-query.sh" export AUTH_SERVICE_URL="https://auth.freshhub.ai"

Quick command discovery

Quick command discovery

[ -f "$OFFICE_CLI" ] && bun "$OFFICE_CLI" status [ -x "$NOTION_CLI" ] && "$NOTION_CLI" me
undefined
[ -f "$OFFICE_CLI" ] && bun "$OFFICE_CLI" status [ -x "$NOTION_CLI" ] && "$NOTION_CLI" me
undefined

Bundled scripts

内置脚本

  • scripts/office-cli.ts
    for Microsoft Graph-backed Drive, Mail, Calendar, and People actions.
  • scripts/notion-query.sh
    for direct Notion API read/write workflows.
  • scripts/office-cli.ts
    ：用于基于Microsoft Graph的驱动器、邮件、日历和人员操作。
  • scripts/notion-query.sh
    ：用于直接的Notion API读写工作流。

Office + Graph: canonical flow

Office + Graph：标准流程

Follow this flow when granting access for Graph-backed tools.
bash
undefined
在为基于Graph的工具授予访问权限时，请遵循以下流程。
bash
undefined

Register and create grants

Register and create grants

bun "$OFFICE_CLI" login bun "$OFFICE_CLI" request drive bun "$OFFICE_CLI" request mail bun "$OFFICE_CLI" request cal
bun "$OFFICE_CLI" login bun "$OFFICE_CLI" request drive bun "$OFFICE_CLI" request mail bun "$OFFICE_CLI" request cal

Verify active grants

Verify active grants

bun "$OFFICE_CLI" status
undefined
bun "$OFFICE_CLI" status
undefined

Command map: Office CLI

Office CLI 命令映射

Drive / Graph storage

驱动器 / Graph 存储

bash
bun "$OFFICE_CLI" drive list
bun "$OFFICE_CLI" drive list "/Documents"
bun "$OFFICE_CLI" drive search "Quarterly report"
bun "$OFFICE_CLI" drive download <file-id> out.docx
bun "$OFFICE_CLI" drive content <file-id>
bun "$OFFICE_CLI" drive convert <file-id> --output=notes.md
bun "$OFFICE_CLI" drive share <file-id> --type edit
bun "$OFFICE_CLI" drive share <file-id> --anyone
bun "$OFFICE_CLI" drive permissions <file-id>
bun "$OFFICE_CLI" drive unshare <file-id> <permission-id>
bash
bun "$OFFICE_CLI" drive list
bun "$OFFICE_CLI" drive list "/Documents"
bun "$OFFICE_CLI" drive search "Quarterly report"
bun "$OFFICE_CLI" drive download <file-id> out.docx
bun "$OFFICE_CLI" drive content <file-id>
bun "$OFFICE_CLI" drive convert <file-id> --output=notes.md
bun "$OFFICE_CLI" drive share <file-id> --type edit
bun "$OFFICE_CLI" drive share <file-id> --anyone
bun "$OFFICE_CLI" drive permissions <file-id>
bun "$OFFICE_CLI" drive unshare <file-id> <permission-id>

Mail / Email

邮件 / Email

bash
bun "$OFFICE_CLI" mail inbox
bun "$OFFICE_CLI" mail inbox --count 50
bun "$OFFICE_CLI" mail unread
bun "$OFFICE_CLI" mail search "team update"
bun "$OFFICE_CLI" mail read <message-id>
bun "$OFFICE_CLI" mail send --to "teammate@example.com" --subject "Brief" --body "Thanks for the update"
bun "$OFFICE_CLI" mail send --to "brad" --subject "Quick check" --body "Approved" --yes
bun "$OFFICE_CLI" mail reply <message-id> --body "Got it."
bun "$OFFICE_CLI" mail reply-all <message-id> --body "Thanks everyone."
bash
bun "$OFFICE_CLI" mail inbox
bun "$OFFICE_CLI" mail inbox --count 50
bun "$OFFICE_CLI" mail unread
bun "$OFFICE_CLI" mail search "team update"
bun "$OFFICE_CLI" mail read <message-id>
bun "$OFFICE_CLI" mail send --to "teammate@example.com" --subject "Brief" --body "Thanks for the update"
bun "$OFFICE_CLI" mail send --to "brad" --subject "Quick check" --body "Approved" --yes
bun "$OFFICE_CLI" mail reply <message-id> --body "Got it."
bun "$OFFICE_CLI" mail reply-all <message-id> --body "Thanks everyone."

Calendar

日历

bash
bun "$OFFICE_CLI" cal today
bun "$OFFICE_CLI" cal tomorrow
bun "$OFFICE_CLI" cal events --days 14
bun "$OFFICE_CLI" cal events --full
bash
bun "$OFFICE_CLI" cal today
bun "$OFFICE_CLI" cal tomorrow
bun "$OFFICE_CLI" cal events --days 14
bun "$OFFICE_CLI" cal events --full

People lookup (Graph contact helper)

人员查询（Graph 联系人助手）

bash
bun "$OFFICE_CLI" people "brad"
bun "$OFFICE_CLI" people "brad" --verbose
bash
bun "$OFFICE_CLI" people "brad"
bun "$OFFICE_CLI" people "brad" --verbose

Notion command map

Notion 命令映射

bash
$NOTION_CLI me
$NOTION_CLI find-db "my database"
$NOTION_CLI search "my database"
$NOTION_CLI get-db <database-id>
$NOTION_CLI query-db <database-id>
$NOTION_CLI get-page <page-id>
$NOTION_CLI get-markdown <page-id>
$NOTION_CLI create <database-id> "Title" -p "Status=In progress" -p "Priority=High"
$NOTION_CLI update <page-id> -p "Status=Done"
$NOTION_CLI set-body <page-id> -
$NOTION_CLI append-body <page-id> -
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
.
bash
$NOTION_CLI me
$NOTION_CLI find-db "my database"
$NOTION_CLI search "my database"
$NOTION_CLI get-db <database-id>
$NOTION_CLI query-db <database-id>
$NOTION_CLI get-page <page-id>
$NOTION_CLI get-markdown <page-id>
$NOTION_CLI create <database-id> "Title" -p "Status=In progress" -p "Priority=High"
$NOTION_CLI update <page-id> -p "Status=Done"
$NOTION_CLI set-body <page-id> -
$NOTION_CLI append-body <page-id> -
当数据库ID未知时，请先使用
find-db
。它会返回数据库的
id
、
title
和
url
，以便直接将ID复制到
get-db
、
query-db
或
create
命令中。

Notion backlog helper

Notion 待办事项助手

bash
undefined
bash
undefined

Optional: enable shortcuts for a specific Notion backlog database

Optional: enable shortcuts for a specific Notion backlog database

export NOTION_BACKLOG_DB_ID="<database-id>"
$NOTION_CLI backlog $NOTION_CLI backlog "In Progress" $NOTION_CLI create-backlog "New task"
undefined
export NOTION_BACKLOG_DB_ID="<database-id>"
$NOTION_CLI backlog $NOTION_CLI backlog "In Progress" $NOTION_CLI create-backlog "New task"
undefined

Multi-tool patterns

多工具使用模式

  • Run 
    people
    first, then 
    mail send --to <resolved email>
    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
    .
  • 先运行
    people
    命令，再执行
    mail send --to <解析后的邮箱>
    ，以实现更安全的身份解析。
  • 使用
    search
    或
    query-db
    提取Notion任务，然后使用
    append-body
    添加上下文。
  • 使用
    drive convert
    将驱动器中的会议PDF转换为Markdown，然后通过
    append-body
    将笔记存储到Notion中。

Error handling

错误处理

  • no_agent_session
    : run 
    bun "$OFFICE_CLI" login
    .
  • no_grant
    : run 
    bun "$OFFICE_CLI" request <drive|mail|cal>
    .
  • token expired
    : run 
    bun "$OFFICE_CLI" status
    and follow the returned re-authorisation URL.
  • NOTION_API_KEY
    missing: set variable and rerun the failing Notion command.
  • 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.
  • no_agent_session
    ：运行
    bun "$OFFICE_CLI" login
    。
  • no_grant
    ：运行
    bun "$OFFICE_CLI" request <drive|mail|cal>
    。
  • token expired
    ：运行
    bun "$OFFICE_CLI" status
    ，并按照返回的重新授权URL操作。
  • NOTION_API_KEY
    缺失：设置该变量后重新运行失败的Notion命令。
  • NOTION_BACKLOG_DB_ID
    缺失：设置该变量，或使用通用的
    query-db
    /
    create
    命令代替待办事项快捷方式。
  • Microsoft账户未关联：按照Graph代理响应输出的URL操作。

Public publication checks

公开发布检查

  • Keep 
    NOTION_API_KEY
    and graph proxy URLs configurable by environment.
  • 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.
  • 保持
    NOTION_API_KEY
    和Graph代理URL可通过环境变量配置。
  • 不要在skill输出中嵌入API密钥或会话ID。
  • 默认情况下，所有命令都指向
    https://auth.freshhub.ai
    。
  • 将两个CLI都包含在此skill的
    scripts/
    文件夹中，以实现自包含安装。
  • 在入门文档中同时提及Microsoft 365和Notion的功能，因为这是统一的用户访问入口。