outnote 0.1.0__tar.gz

outnote-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PianoNic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in 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, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

outnote-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: outnote
+Version: 0.1.0
+Summary: Headless Microsoft 365 reader - mail, calendar, Teams, OneDrive, SharePoint and OneNote over Graph, no app registration.
+Keywords: microsoft,microsoft-365,microsoft-graph,graph-api,outlook,onenote,onedrive,sharepoint,teams,mail,calendar,headless,no-app-registration,foci,entra,mcp
+Author: PianoNic
+Author-email: PianoNic <contact@pianonic.ch>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: ms-entrance>=1.2
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/PianoNic/OutNote
+Project-URL: Issues, https://github.com/PianoNic/OutNote/issues
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/outnote-icon.svg" width="140" alt="OutNote Logo">
+</p>
+
+<h1 align="center">OutNote</h1>
+
+<p align="center">
+  <strong>Headless Microsoft 365 reader - mail, calendar, Teams, OneDrive, SharePoint and OneNote over Graph, without an app registration.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/PianoNic/OutNote"><img src="https://badgetrack.pianonic.ch/badge?tag=outnote&label=visits&color=7719AA&style=flat" alt="visits"/></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-7719AA" alt="Python 3.10+"/>
+  <a href="https://github.com/PianoNic/OutNote/releases"><img src="https://img.shields.io/github/v/release/PianoNic/OutNote?include_prereleases&color=7719AA&label=Latest%20Release" alt="Latest release"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-7719AA.svg" alt="MIT license"/></a>
+  <a href="https://github.com/PianoNic/Entrance"><img src="https://img.shields.io/badge/built%20on-entrance-7719AA.svg" alt="Built on Entrance"/></a>
+</p>
+
+> [!WARNING]
+> **For educational and research purposes only.** Use it solely against **accounts you own** or with the **explicit authorization** of the account/tenant owner. It drives a real sign-in with real credentials - treat the cookie jar and any tokens like passwords. See the [Disclaimer](#disclaimer) below.
+
+## About The Project
+
+Every "read my mailbox over Graph" tutorial makes you register an Azure app and get **admin consent** - which a locked-down tenant (a school, a company) simply refuses. OutNote sidesteps that entirely.
+
+It signs in with [`entrance`](https://github.com/PianoNic/Entrance) using the pre-consented **OfficeHome** first-party client, which hands back a **FOCI family refresh token**. A tiny broker then trades that token for whichever first-party client's Graph token a given call needs - all without another sign-in. Each of those clients is already consented in the tenant, so there is **nothing to register and nobody to ask**.
+
+The result: one headless login (password + TOTP MFA, no browser), then clean Graph reads across your whole Microsoft 365 account. Built to be the base layer for an MCP server.
+
+## Features
+
+- 🔓 **No app registration, no admin consent** - rides pre-consented Microsoft first-party clients
+- 🤖 **Fully headless** - password + TOTP MFA over pure HTTP, no browser (via [`entrance`](https://github.com/PianoNic/Entrance))
+- 🧩 **One login, every service** - a FOCI family token is brokered into the right client per call
+- 📬 **Broad coverage** - mail, calendar, Teams chats & channels, channel files, OneDrive, SharePoint, OneNote
+- 🍪 **Silent reuse** - a persisted session jar means password-free reruns
+- 📦 **Tiny** - stdlib `urllib` Graph client, one dependency (`ms-entrance`)
+
+## Installation
+
+```bash
+pip install outnote
+# or
+uv add outnote
+```
+
+Requires Python 3.10+; `ms-entrance` is pulled in automatically.
+
+## Quickstart
+
+```python
+from outnote import authenticate
+
+note = authenticate(
+    "you@school.ch",
+    "your-password",
+    totp_secret="JBSWY3DPEHPK3PXP",  # Base32 TOTP, if the account has MFA
+)
+
+# mail & calendar
+note.emails(top=5)
+note.events(top=5)
+
+# Teams chats
+for chat in note.chats():
+    note.chat_messages(chat["id"])
+
+# Teams channels + files
+for team in note.teams():
+    for ch in note.channels(team["id"]):
+        note.channel_messages(team["id"], ch["id"])
+        note.channel_files(team["id"], ch["id"])  # files posted in the channel
+
+# OneDrive & SharePoint
+note.files()  # OneDrive items
+note.download_url(item_id)  # direct, pre-authed download link
+note.sites()  # SharePoint sites
+
+# search across the account
+note.search_emails("invoice")
+note.search_files("budget.xlsx")
+note.search_messages("standup")  # Teams chat & channel messages
+note.search_people("Fischer")
+note.search("project kickoff", entity="event")  # any entity type
+
+# OneNote - list and read page content as HTML
+for nb in note.notebooks():
+    for sec in note.sections(nb["id"]):
+        for page in note.pages(sec["id"]):
+            html = note.page_content(page["id"])
+
+note.get("me/drive/root/children")  # any Graph endpoint, raw
+```
+
+The first call saves `.ms_session.json`; every call after that skips the password and MFA.
+
+**Already have a Graph token** (MSAL, a browser session, ...)? Skip auth entirely. A single static token only carries its own scopes, so OneNote/SharePoint calls may `403` if it lacks them:
+
+```python
+from outnote import OutNote
+
+OutNote(access_token).emails()
+```
+
+## What it does
+
+Verified end-to-end against a live locked-down EDU tenant:
+
+| Area | Methods | Graph endpoint |
+|---|---|---|
+| Mail | `emails()`, `email(id)` | `/me/mailFolders/{f}/messages` |
+| Calendar | `events(start, end)` | `/me/events`, `/me/calendarView` |
+| Teams chats | `chats()`, `chat_messages(id)` | `/me/chats`, `/me/chats/{id}/messages` |
+| Teams channels | `teams()`, `channels(t)`, `channel_messages(t, c)` | `/me/joinedTeams`, `/teams/{t}/channels[/{c}/messages]` |
+| Channel files | `channel_files(t, c)` | `filesFolder` → `/drives/{d}/items/{i}/children` |
+| OneDrive | `files(path)`, `download_url(id[, drive_id])` | `/me/drive/...` |
+| SharePoint | `sites(search)`, `site_drive_items(id)` | `/sites`, `/sites/{id}/drive` |
+| OneNote | `notebooks()`, `sections(nb)`, `pages(sec)`, `page_content(id)` | `/me/onenote/...` |
+| Contacts / Tasks | `contacts()`, `task_lists()`, `tasks(list)` | `/me/contacts`, `/me/todo/lists` |
+| Search | `search_emails(q)`, `search_files(q)`, `search_messages(q)`, `search_people(q)`, `search(q, entity)` | `/search/query` (message, driveItem, chatMessage, event, person, site) |
+| Anything | `get(path)`, `list(path)` | any endpoint, follows `@odata.nextLink` |
+
+## How It Works
+
+`authenticate` runs a PKCE authorization-code sign-in for the **OfficeHome** client through `entrance` (which drives Microsoft's sign-in - including TOTP MFA - over pure HTTP and intercepts the `code` at the native-client redirect), then redeems it for a **FOCI family refresh token**. The `OutNote` client holds a broker that, per call, refreshes that token into the first-party client whose pre-consented scopes cover the request, caching each token until it expires:
+
+| Service | FOCI client | Key scope it carries |
+|---|---|---|
+| Mail, Calendar, Chats, Channels, Files, Teams, Contacts, Tasks | Office `d3590ed6-...` | `Mail.ReadWrite`, `Chat.ReadWrite`, `ChannelMessage.Read.All`, `Files.ReadWrite.All`, `Calendars.ReadWrite` |
+| OneNote (read page content) | Teams-classic `1fec8e78-...` | `Notes.ReadWrite.All` |
+| SharePoint sites | OfficeHome `4765445b-...` | `Sites.Read.All` |
+
+Which first-party clients are FOCI-family and pre-consented is tenant-dependent; the three above work on a standard Microsoft 365 / EDU tenant.
+
+## Caveats
+
+- Works against **managed** Entra tenants (`login.microsoftonline.com`) with these first-party clients pre-consented - the common case for Microsoft 365 / EDU.
+- **Push / SMS MFA can't be done headless** - only TOTP (authenticator app). Enroll one and pass its Base32 secret.
+- Microsoft tweaks its login pages and client registrations; if a flow breaks, a user-agent, field name or client ID is usually the culprit.
+
+## Disclaimer
+
+OutNote is published for **educational and research purposes only** - to document how Microsoft 365's first-party OAuth2 clients and the Graph API behave for a browserless client.
+
+Use it only against accounts you own, or with the explicit authorization of the account or tenant owner. You alone are responsible for your use of it and for complying with Microsoft's terms, your identity provider's terms, your institution's acceptable-use policy, and applicable law. The software is provided "as is", without warranty of any kind, and the author accepts no liability for misuse. Not affiliated with or endorsed by Microsoft.
+
+## License
+
+[MIT](LICENSE) (c) [PianoNic](https://github.com/PianoNic)

outnote-0.1.0/README.md

@@ -0,0 +1,149 @@
+<p align="center">
+  <img src="assets/outnote-icon.svg" width="140" alt="OutNote Logo">
+</p>
+
+<h1 align="center">OutNote</h1>
+
+<p align="center">
+  <strong>Headless Microsoft 365 reader - mail, calendar, Teams, OneDrive, SharePoint and OneNote over Graph, without an app registration.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/PianoNic/OutNote"><img src="https://badgetrack.pianonic.ch/badge?tag=outnote&label=visits&color=7719AA&style=flat" alt="visits"/></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-7719AA" alt="Python 3.10+"/>
+  <a href="https://github.com/PianoNic/OutNote/releases"><img src="https://img.shields.io/github/v/release/PianoNic/OutNote?include_prereleases&color=7719AA&label=Latest%20Release" alt="Latest release"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-7719AA.svg" alt="MIT license"/></a>
+  <a href="https://github.com/PianoNic/Entrance"><img src="https://img.shields.io/badge/built%20on-entrance-7719AA.svg" alt="Built on Entrance"/></a>
+</p>
+
+> [!WARNING]
+> **For educational and research purposes only.** Use it solely against **accounts you own** or with the **explicit authorization** of the account/tenant owner. It drives a real sign-in with real credentials - treat the cookie jar and any tokens like passwords. See the [Disclaimer](#disclaimer) below.
+
+## About The Project
+
+Every "read my mailbox over Graph" tutorial makes you register an Azure app and get **admin consent** - which a locked-down tenant (a school, a company) simply refuses. OutNote sidesteps that entirely.
+
+It signs in with [`entrance`](https://github.com/PianoNic/Entrance) using the pre-consented **OfficeHome** first-party client, which hands back a **FOCI family refresh token**. A tiny broker then trades that token for whichever first-party client's Graph token a given call needs - all without another sign-in. Each of those clients is already consented in the tenant, so there is **nothing to register and nobody to ask**.
+
+The result: one headless login (password + TOTP MFA, no browser), then clean Graph reads across your whole Microsoft 365 account. Built to be the base layer for an MCP server.
+
+## Features
+
+- 🔓 **No app registration, no admin consent** - rides pre-consented Microsoft first-party clients
+- 🤖 **Fully headless** - password + TOTP MFA over pure HTTP, no browser (via [`entrance`](https://github.com/PianoNic/Entrance))
+- 🧩 **One login, every service** - a FOCI family token is brokered into the right client per call
+- 📬 **Broad coverage** - mail, calendar, Teams chats & channels, channel files, OneDrive, SharePoint, OneNote
+- 🍪 **Silent reuse** - a persisted session jar means password-free reruns
+- 📦 **Tiny** - stdlib `urllib` Graph client, one dependency (`ms-entrance`)
+
+## Installation
+
+```bash
+pip install outnote
+# or
+uv add outnote
+```
+
+Requires Python 3.10+; `ms-entrance` is pulled in automatically.
+
+## Quickstart
+
+```python
+from outnote import authenticate
+
+note = authenticate(
+    "you@school.ch",
+    "your-password",
+    totp_secret="JBSWY3DPEHPK3PXP",  # Base32 TOTP, if the account has MFA
+)
+
+# mail & calendar
+note.emails(top=5)
+note.events(top=5)
+
+# Teams chats
+for chat in note.chats():
+    note.chat_messages(chat["id"])
+
+# Teams channels + files
+for team in note.teams():
+    for ch in note.channels(team["id"]):
+        note.channel_messages(team["id"], ch["id"])
+        note.channel_files(team["id"], ch["id"])  # files posted in the channel
+
+# OneDrive & SharePoint
+note.files()  # OneDrive items
+note.download_url(item_id)  # direct, pre-authed download link
+note.sites()  # SharePoint sites
+
+# search across the account
+note.search_emails("invoice")
+note.search_files("budget.xlsx")
+note.search_messages("standup")  # Teams chat & channel messages
+note.search_people("Fischer")
+note.search("project kickoff", entity="event")  # any entity type
+
+# OneNote - list and read page content as HTML
+for nb in note.notebooks():
+    for sec in note.sections(nb["id"]):
+        for page in note.pages(sec["id"]):
+            html = note.page_content(page["id"])
+
+note.get("me/drive/root/children")  # any Graph endpoint, raw
+```
+
+The first call saves `.ms_session.json`; every call after that skips the password and MFA.
+
+**Already have a Graph token** (MSAL, a browser session, ...)? Skip auth entirely. A single static token only carries its own scopes, so OneNote/SharePoint calls may `403` if it lacks them:
+
+```python
+from outnote import OutNote
+
+OutNote(access_token).emails()
+```
+
+## What it does
+
+Verified end-to-end against a live locked-down EDU tenant:
+
+| Area | Methods | Graph endpoint |
+|---|---|---|
+| Mail | `emails()`, `email(id)` | `/me/mailFolders/{f}/messages` |
+| Calendar | `events(start, end)` | `/me/events`, `/me/calendarView` |
+| Teams chats | `chats()`, `chat_messages(id)` | `/me/chats`, `/me/chats/{id}/messages` |
+| Teams channels | `teams()`, `channels(t)`, `channel_messages(t, c)` | `/me/joinedTeams`, `/teams/{t}/channels[/{c}/messages]` |
+| Channel files | `channel_files(t, c)` | `filesFolder` → `/drives/{d}/items/{i}/children` |
+| OneDrive | `files(path)`, `download_url(id[, drive_id])` | `/me/drive/...` |
+| SharePoint | `sites(search)`, `site_drive_items(id)` | `/sites`, `/sites/{id}/drive` |
+| OneNote | `notebooks()`, `sections(nb)`, `pages(sec)`, `page_content(id)` | `/me/onenote/...` |
+| Contacts / Tasks | `contacts()`, `task_lists()`, `tasks(list)` | `/me/contacts`, `/me/todo/lists` |
+| Search | `search_emails(q)`, `search_files(q)`, `search_messages(q)`, `search_people(q)`, `search(q, entity)` | `/search/query` (message, driveItem, chatMessage, event, person, site) |
+| Anything | `get(path)`, `list(path)` | any endpoint, follows `@odata.nextLink` |
+
+## How It Works
+
+`authenticate` runs a PKCE authorization-code sign-in for the **OfficeHome** client through `entrance` (which drives Microsoft's sign-in - including TOTP MFA - over pure HTTP and intercepts the `code` at the native-client redirect), then redeems it for a **FOCI family refresh token**. The `OutNote` client holds a broker that, per call, refreshes that token into the first-party client whose pre-consented scopes cover the request, caching each token until it expires:
+
+| Service | FOCI client | Key scope it carries |
+|---|---|---|
+| Mail, Calendar, Chats, Channels, Files, Teams, Contacts, Tasks | Office `d3590ed6-...` | `Mail.ReadWrite`, `Chat.ReadWrite`, `ChannelMessage.Read.All`, `Files.ReadWrite.All`, `Calendars.ReadWrite` |
+| OneNote (read page content) | Teams-classic `1fec8e78-...` | `Notes.ReadWrite.All` |
+| SharePoint sites | OfficeHome `4765445b-...` | `Sites.Read.All` |
+
+Which first-party clients are FOCI-family and pre-consented is tenant-dependent; the three above work on a standard Microsoft 365 / EDU tenant.
+
+## Caveats
+
+- Works against **managed** Entra tenants (`login.microsoftonline.com`) with these first-party clients pre-consented - the common case for Microsoft 365 / EDU.
+- **Push / SMS MFA can't be done headless** - only TOTP (authenticator app). Enroll one and pass its Base32 secret.
+- Microsoft tweaks its login pages and client registrations; if a flow breaks, a user-agent, field name or client ID is usually the culprit.
+
+## Disclaimer
+
+OutNote is published for **educational and research purposes only** - to document how Microsoft 365's first-party OAuth2 clients and the Graph API behave for a browserless client.
+
+Use it only against accounts you own, or with the explicit authorization of the account or tenant owner. You alone are responsible for your use of it and for complying with Microsoft's terms, your identity provider's terms, your institution's acceptable-use policy, and applicable law. The software is provided "as is", without warranty of any kind, and the author accepts no liability for misuse. Not affiliated with or endorsed by Microsoft.
+
+## License
+
+[MIT](LICENSE) (c) [PianoNic](https://github.com/PianoNic)

outnote-0.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+[build-system]
+requires = ["uv_build >= 0.11.7, <0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "outnote"
+version = "0.1.0"
+description = "Headless Microsoft 365 reader - mail, calendar, Teams, OneDrive, SharePoint and OneNote over Graph, no app registration."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+keywords = [
+    "microsoft",
+    "microsoft-365",
+    "microsoft-graph",
+    "graph-api",
+    "outlook",
+    "onenote",
+    "onedrive",
+    "sharepoint",
+    "teams",
+    "mail",
+    "calendar",
+    "headless",
+    "no-app-registration",
+    "foci",
+    "entra",
+    "mcp",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Office/Business",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["ms-entrance>=1.2"]
+
+[[project.authors]]
+name = "PianoNic"
+email = "contact@pianonic.ch"
+
+[project.urls]
+Homepage = "https://github.com/PianoNic/OutNote"
+Issues = "https://github.com/PianoNic/OutNote/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "mypy>=1.10",
+    "ruff>=0.6",
+]
+
+[tool.uv.build-backend]
+module-name = "outnote"
+module-root = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]
+ignore = [
+    "E501",
+    "E731",
+    "B008",
+]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+files = ["src/outnote"]

outnote-0.1.0/pyproject.toml.orig

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["uv_build >= 0.11.7, <0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "outnote"
+version = "0.1.0"
+description = "Headless Microsoft 365 reader - mail, calendar, Teams, OneDrive, SharePoint and OneNote over Graph, no app registration."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "PianoNic", email = "contact@pianonic.ch" },
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+keywords = [
+    "microsoft",
+    "microsoft-365",
+    "microsoft-graph",
+    "graph-api",
+    "outlook",
+    "onenote",
+    "onedrive",
+    "sharepoint",
+    "teams",
+    "mail",
+    "calendar",
+    "headless",
+    "no-app-registration",
+    "foci",
+    "entra",
+    "mcp",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Office/Business",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "ms-entrance>=1.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/PianoNic/OutNote"
+Issues = "https://github.com/PianoNic/OutNote/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "mypy>=1.10",
+    "ruff>=0.6",
+]
+
+[tool.uv.build-backend]
+module-name = "outnote"
+module-root = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501", "E731", "B008"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+files = ["src/outnote"]

outnote-0.1.0/src/outnote/__init__.py

@@ -0,0 +1,30 @@
+"""OutNote — read Microsoft 365 over Graph, headless, no app registration.
+
+    from outnote import authenticate
+    note = authenticate("you@org.com", "password", totp_secret="BASE32")
+
+    note.emails()                      # mail
+    note.events()                      # calendar
+    note.chats(); note.chat_messages(id)        # Teams chats
+    note.teams(); note.channel_messages(t, c)   # Teams channels
+    note.channel_files(t, c)                    # files posted in a channel
+    note.files()                       # OneDrive
+    note.sites()                       # SharePoint
+    note.notebooks(); note.pages(sec); note.page_content(id)   # OneNote
+
+One sign-in yields a FOCI family refresh token; a broker mints the right
+first-party client's token per call. Already have a token? `OutNote(token)`.
+"""
+
+from ._auth import OFFICEHOME, authenticate
+from ._graph import C_OFFICE, C_ONENOTE, C_SITES, GraphError, OutNote
+
+__all__ = [
+    "OutNote",
+    "authenticate",
+    "GraphError",
+    "OFFICEHOME",
+    "C_OFFICE",
+    "C_ONENOTE",
+    "C_SITES",
+]

outnote-0.1.0/src/outnote/_auth.py

@@ -0,0 +1,151 @@
+"""Headless Microsoft 365 sign-in that needs no app registration.
+
+One sign-in (via `entrance`) against the pre-consented OfficeHome client yields
+a FOCI **family refresh token**; a broker then mints a Graph token for whichever
+first-party client a given call needs — all without further sign-ins. See the
+README for the token map and the (accounts-you-own) disclaimer.
+"""
+
+import base64
+import hashlib
+import json
+import secrets
+import time
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from ._graph import OutNote
+
+_AUTHORIZE = "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize"
+_TOKEN = "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token"
+
+# The sign-in client: OfficeHome is pre-consented and issues a FOCI (family=1)
+# refresh token that the broker trades for the other family clients' tokens.
+OFFICEHOME = "4765445b-32c6-49b0-83e6-1d93765276ca"
+# Native-client redirect: redeems server-side (no SPA/Origin dance). entrance
+# intercepts the code here; it is never actually delivered.
+_REDIRECT = "https://login.microsoftonline.com/common/oauth2/nativeclient"
+_SCOPES = "https://graph.microsoft.com/.default offline_access openid profile"
+
+
+def _pkce():
+    v = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
+    c = base64.urlsafe_b64encode(hashlib.sha256(v.encode()).digest()).rstrip(b"=").decode()
+    return v, c
+
+
+def _post_token(url, data):
+    req = Request(
+        url,
+        data=urlencode(data).encode(),
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+    )
+    try:
+        with urlopen(req) as r:  # noqa: S310 - fixed https host
+            return json.loads(r.read())
+    except Exception as e:  # noqa: BLE001 - surface the AADSTS error body
+        body = getattr(e, "read", lambda: b"")()
+        try:
+            return json.loads(body)
+        except ValueError:
+            raise RuntimeError(f"Token endpoint error: {e}") from None
+
+
+class _Broker:
+    """Holds a FOCI family refresh token and mints/caches a Graph access token
+    per first-party client on demand. Callable as `broker(client_id) -> token`."""
+
+    def __init__(self, refresh_token, tenant="common"):
+        self._frt = refresh_token
+        self._url = _TOKEN.format(tenant=tenant)
+        self._cache = {}  # client_id -> (access_token, expiry_epoch)
+
+    def __call__(self, client_id):
+        tok, exp = self._cache.get(client_id, (None, 0))
+        if tok and exp - 60 > time.time():
+            return tok
+        r = _post_token(
+            self._url,
+            {
+                "grant_type": "refresh_token",
+                "refresh_token": self._frt,
+                "client_id": client_id,
+                "scope": "https://graph.microsoft.com/.default",
+            },
+        )
+        if not r.get("access_token"):
+            raise RuntimeError(
+                f"Could not get a token for client {client_id}: {r.get('error_description') or r}"
+            )
+        self._frt = r.get("refresh_token", self._frt)  # FRT rotates on use
+        self._cache[client_id] = (r["access_token"], time.time() + r.get("expires_in", 3600))
+        return r["access_token"]
+
+
+def authenticate(
+    username=None,
+    password=None,
+    *,
+    tenant="common",
+    totp_secret=None,
+    totp_code=None,
+    cookies=".ms_session.json",
+    **login_kwargs,
+):
+    """Sign in and return an `OutNote` client wired to a token broker.
+
+    No app registration or admin consent needed. `username`/`password` are
+    optional once `cookies` holds a live session (silent reuse). MFA: pass
+    `totp_secret` (Base32) or `totp_code`. Extra kwargs pass through to
+    `entrance.login`.
+    """
+    from entrance import login  # deferred: only the sign-in path needs entrance
+
+    verifier, challenge = _pkce()
+    authorize_url = (
+        _AUTHORIZE.format(tenant=tenant)
+        + "?"
+        + urlencode(
+            {
+                "client_id": OFFICEHOME,
+                "response_type": "code",
+                "redirect_uri": _REDIRECT,
+                "response_mode": "query",
+                "scope": _SCOPES,
+                "state": secrets.token_urlsafe(16),
+                "code_challenge": challenge,
+                "code_challenge_method": "S256",
+            }
+        )
+    )
+
+    res = login(
+        authorize_url,
+        username=username,
+        password=password,
+        totp_secret=totp_secret,
+        totp_code=totp_code,
+        code_verifier=verifier,
+        redirect_uri=_REDIRECT,
+        cookies=cookies,
+        **login_kwargs,
+    )
+    if not res.get("code"):
+        raise RuntimeError("No authorization code intercepted; keys: " + ", ".join(res))
+
+    tokens = _post_token(
+        _TOKEN.format(tenant=tenant),
+        {
+            "grant_type": "authorization_code",
+            "code": res["code"],
+            "client_id": OFFICEHOME,
+            "redirect_uri": _REDIRECT,
+            "code_verifier": verifier,
+        },
+    )
+    frt = tokens.get("refresh_token")
+    if not frt:
+        raise RuntimeError(
+            f"No refresh token from sign-in: {tokens.get('error_description') or tokens}"
+        )
+    return OutNote(_Broker(frt, tenant))

outnote-0.1.0/src/outnote/_graph.py

@@ -0,0 +1,240 @@
+"""Microsoft Graph client for mail, calendar, chats, channels, files,
+SharePoint and OneNote.
+
+Each method routes to the pre-consented first-party client whose token carries
+the scope it needs (see `authenticate` / the README token map). Graph is just
+GET + Bearer + JSON, so this leans on stdlib urllib.
+"""
+
+import json
+from urllib.error import HTTPError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+GRAPH = "https://graph.microsoft.com/v1.0"
+_MAX_PAGES = 50  # ponytail: hard stop so follow-the-nextLink can't loop forever
+
+# FOCI family clients, each pre-consented for the scopes that service needs.
+C_OFFICE = "d3590ed6-52b3-4102-aeff-aad2292ab01c"  # mail, calendar, chat, channels, files, teams, contacts, tasks
+C_ONENOTE = "1fec8e78-bce4-4aaf-ab1b-5451cc387264"  # OneNote (Notes.ReadWrite.All)
+C_SITES = "4765445b-32c6-49b0-83e6-1d93765276ca"  # SharePoint sites (Sites.Read.All)
+
+# which client's token each unified-search entity type needs
+_SEARCH_CLIENT = {
+    "message": C_OFFICE,
+    "event": C_OFFICE,
+    "driveItem": C_OFFICE,
+    "chatMessage": C_OFFICE,
+    "person": C_OFFICE,
+    "site": C_SITES,
+    "listItem": C_SITES,
+}
+
+
+class GraphError(RuntimeError):
+    def __init__(self, status, message):
+        self.status = status
+        super().__init__(f"Graph {status}: {message}")
+
+
+class OutNote:
+    def __init__(self, token, base=GRAPH):
+        """`token` is either an access-token string (used for every call) or a
+        callable `client_id -> access_token` (the broker from `authenticate`,
+        which hands each service the right client's token)."""
+        if not token:
+            raise ValueError("token is required")
+        self._tp = token if callable(token) else (lambda _client: token)
+        self.token = token if isinstance(token, str) else None
+        self.base = base.rstrip("/")
+
+    # --- transport ----------------------------------------------------------
+    def _url(self, path, params=None):
+        url = path if path.startswith("http") else self.base + "/" + path.lstrip("/")
+        if params:
+            q = urlencode({k: v for k, v in params.items() if v is not None})
+            if q:
+                url += ("&" if "?" in url else "?") + q
+        return url
+
+    def _send(self, req, raw=False):
+        try:
+            with urlopen(req) as r:  # noqa: S310 - fixed https host
+                body = r.read()
+        except HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")
+            try:
+                detail = json.loads(detail)["error"]["message"]
+            except (ValueError, KeyError, TypeError):
+                pass
+            raise GraphError(e.code, detail) from None
+        return body.decode("utf-8") if raw else json.loads(body)
+
+    def get(self, path, params=None, raw=False, client=C_OFFICE):
+        """One GET against `client`'s token. `raw=True` returns body text
+        (OneNote page content is HTML, not JSON)."""
+        req = Request(
+            self._url(path, params),
+            headers={"Authorization": f"Bearer {self._tp(client)}", "Accept": "application/json"},
+        )
+        return self._send(req, raw)
+
+    def post(self, path, body, client=C_OFFICE):
+        """One POST of a JSON body against `client`'s token."""
+        req = Request(
+            self._url(path),
+            data=json.dumps(body).encode(),
+            headers={
+                "Authorization": f"Bearer {self._tp(client)}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+        )
+        return self._send(req)
+
+    def list(self, path, params=None, limit=None, client=C_OFFICE):
+        """GET a collection, following @odata.nextLink; returns the combined
+        `value` list, capped at `limit` items (and _MAX_PAGES pages)."""
+        out = []
+        url = self._url(path, params)
+        for _ in range(_MAX_PAGES):
+            page = self.get(url, client=client)
+            out.extend(page.get("value", []))
+            if limit and len(out) >= limit:
+                return out[:limit]
+            url = page.get("@odata.nextLink")
+            if not url:
+                break
+        return out
+
+    # --- mail ---------------------------------------------------------------
+    def emails(self, folder="inbox", top=25, search=None, select=None):
+        params = {"$top": top, "$select": select}
+        if search:
+            params["$search"] = f'"{search}"'
+        else:
+            params["$orderby"] = "receivedDateTime desc"
+        return self.list(f"me/mailFolders/{folder}/messages", params, limit=top)
+
+    def email(self, message_id):
+        return self.get(f"me/messages/{message_id}")
+
+    # --- calendar -----------------------------------------------------------
+    def events(self, start=None, end=None, top=25):
+        if start and end:
+            params = {
+                "startDateTime": start,
+                "endDateTime": end,
+                "$top": top,
+                "$orderby": "start/dateTime",
+            }
+            return self.list("me/calendarView", params, limit=top)
+        return self.list("me/events", {"$top": top, "$orderby": "start/dateTime"}, limit=top)
+
+    # --- teams: chats -------------------------------------------------------
+    def chats(self, top=25):
+        """1:1 and group chats."""
+        return self.list("me/chats", {"$top": top}, limit=top)
+
+    def chat_messages(self, chat_id, top=30):
+        return self.list(f"me/chats/{chat_id}/messages", {"$top": top}, limit=top)
+
+    # --- teams: teams & channels --------------------------------------------
+    def teams(self):
+        return self.list("me/joinedTeams")
+
+    def channels(self, team_id):
+        return self.list(f"teams/{team_id}/channels")
+
+    def channel_messages(self, team_id, channel_id, top=30):
+        return self.list(
+            f"teams/{team_id}/channels/{channel_id}/messages", {"$top": top}, limit=top
+        )
+
+    def channel_files(self, team_id, channel_id):
+        """Files posted in a channel (the channel's SharePoint folder)."""
+        ff = self.get(f"teams/{team_id}/channels/{channel_id}/filesFolder")
+        drive, item = ff["parentReference"]["driveId"], ff["id"]
+        return self.list(f"drives/{drive}/items/{item}/children")
+
+    # --- files / onedrive / sharepoint --------------------------------------
+    def files(self, path="root", top=100):
+        """OneDrive items. `path` is 'root' or 'root:/Folder/Sub:'."""
+        return self.list(f"me/drive/{path}/children", {"$top": top}, limit=top)
+
+    def download_url(self, item_id, drive_id=None):
+        """A direct, pre-authed download URL for a drive item (works for OneDrive
+        and channel files — pass the item's drive_id for the latter)."""
+        base = f"drives/{drive_id}/items/{item_id}" if drive_id else f"me/drive/items/{item_id}"
+        return self.get(base).get("@microsoft.graph.downloadUrl")
+
+    def sites(self, search="*"):
+        return self.list(f"sites?search={search}", client=C_SITES)
+
+    def site_drive_items(self, site_id, path="root", top=100):
+        return self.list(
+            f"sites/{site_id}/drive/{path}/children", {"$top": top}, limit=top, client=C_SITES
+        )
+
+    # --- onenote ------------------------------------------------------------
+    def notebooks(self):
+        return self.list("me/onenote/notebooks", client=C_ONENOTE)
+
+    def sections(self, notebook_id=None):
+        path = (
+            f"me/onenote/notebooks/{notebook_id}/sections" if notebook_id else "me/onenote/sections"
+        )
+        return self.list(path, client=C_ONENOTE)
+
+    def pages(self, section_id, top=50):
+        """Pages in a section. (List per-section — the all-pages endpoint is
+        flaky.)"""
+        return self.list(
+            f"me/onenote/sections/{section_id}/pages", {"$top": top}, limit=top, client=C_ONENOTE
+        )
+
+    def page_content(self, page_id):
+        """A OneNote page's body as HTML (string)."""
+        return self.get(f"me/onenote/pages/{page_id}/content", raw=True, client=C_ONENOTE)
+
+    # --- people / tasks -----------------------------------------------------
+    def contacts(self, top=50):
+        return self.list("me/contacts", {"$top": top}, limit=top)
+
+    def task_lists(self):
+        return self.list("me/todo/lists")
+
+    def tasks(self, list_id, top=50):
+        return self.list(f"me/todo/lists/{list_id}/tasks", {"$top": top}, limit=top)
+
+    # --- search (unified Graph /search/query) -------------------------------
+    def search(self, query, entity="message", top=25):
+        """Search one entity type across the account and return the matched
+        resources. `entity` is one of: 'message' (email), 'driveItem' (files),
+        'chatMessage' (Teams chat/channel messages), 'event' (calendar),
+        'person', 'site', 'listItem'. (Graph only allows one of these per
+        request, so search one kind at a time.)"""
+        client = _SEARCH_CLIENT.get(entity, C_OFFICE)
+        body = {
+            "requests": [{"entityTypes": [entity], "query": {"queryString": query}, "size": top}]
+        }
+        data = self.post("search/query", body, client=client)
+        containers = (data.get("value") or [{}])[0].get("hitsContainers") or []
+        hits = containers[0].get("hits", []) if containers else []
+        return [h["resource"] for h in hits]
+
+    def search_emails(self, query, top=25):
+        return self.search(query, "message", top)
+
+    def search_files(self, query, top=25):
+        return self.search(query, "driveItem", top)
+
+    def search_messages(self, query, top=25):
+        """Search Teams chat and channel messages."""
+        return self.search(query, "chatMessage", top)
+
+    def search_people(self, query, top=25):
+        return self.search(query, "person", top)
+
+    def me(self):
+        return self.get("me")