VagabondK.nF.Web
0.1.0-preview.7
dotnet add package VagabondK.nF.Web --version 0.1.0-preview.7
NuGet\Install-Package VagabondK.nF.Web -Version 0.1.0-preview.7
<PackageReference Include="VagabondK.nF.Web" Version="0.1.0-preview.7" />
<PackageVersion Include="VagabondK.nF.Web" Version="0.1.0-preview.7" />
<PackageReference Include="VagabondK.nF.Web" />
paket add VagabondK.nF.Web --version 0.1.0-preview.7
#r "nuget: VagabondK.nF.Web, 0.1.0-preview.7"
#:package VagabondK.nF.Web@0.1.0-preview.7
#addin nuget:?package=VagabondK.nF.Web&version=0.1.0-preview.7&prerelease
#tool nuget:?package=VagabondK.nF.Web&version=0.1.0-preview.7&prerelease
VagabondK.nF.Web
주요 기능: GuardedWebServer fail-closed 인증, LoginGuard/토큰 저장소, 표준 인증 API(AuthController), JSON 헬퍼
본 리포지토리는 제가 개인적으로 .NET nanoFramework를 사용할 때 편리하게 활용하기 위해 필요한 기능을 만들어 놓은 라이브러리 세트입니다.
이 패키지는 .NET nanoFramework 앱에 임베드되는 웹 인증 레이어입니다. GuardedWebServer가 인증되지 않은 요청을 차단(fail-closed)하고, LoginGuard·세션·토큰 저장소와 표준 인증 API(AuthController)를 제공합니다. 정적 페이지와 리소스는 VagabondK.nF.WebUi로 빌드 타임에 생성합니다.
설치
Visual Studio의 nanoFramework 프로젝트에서 NuGet 패키지 관리자를 열고 사전 릴리스 포함을 선택하십시오. 이 평가 패키지를 보관한 로컬 피드와 공식 nanoFramework 의존성을 받을 수 있는 소스를 등록한 뒤 설치합니다. 패키지 관리자 콘솔에서는 대상 nanoFramework 프로젝트를 선택하고 다음 명령을 사용합니다.
Install-Package VagabondK.nF.Web -Version 0.1.0-preview.7
용도와 구성
Web 계열은 장치에서 실행되는 인증 레이어(Web)와 PC 빌드 때 페이지 리소스를 만드는 생성기(WebUi)로 구성됩니다. 하나만 설치하면 다른 쪽 기능이 자동으로 추가되지 않으며, 브라우저 페이지를 제공하려면 두 패키지를 함께 사용합니다.
아래 이름에는 VagabondK.nF. 접두사를 붙입니다. 공통 코어는 의존성으로 설치됩니다.
- 관리 화면: Web + WebUi
- 인증 API만 사용: Web 단독(직접 만든 컨트롤러 연결)
- 페이지 리소스만 생성: WebUi + 임의의 HTTP 서버
이 패키지의 직접 의존성
다른 VagabondK.nF 런타임 패키지에 직접 의존하지 않습니다.
NuGet은 이 패키지뿐 아니라 의존하는 패키지도 함께 설치합니다. 필요한 nanoFramework 시스템 패키지와 버전은 패키지 메타데이터에서 확인할 수 있습니다.
기능과 사용법
단일 관리자 비밀번호 기반의 임베디드 웹 인증 파사드입니다. 평문 비밀번호를 저장하지 않고, 솔트+HMAC-SHA256 반복 해시와 메모리 세션 토큰을 사용합니다.
nanoFramework.WebServer를 직접 참조하므로 인증·응답·CSRF 계층까지 한 어셈블리로
관리 화면을 완성할 수 있습니다(참조: nanoFramework.WebServer, nanoFramework.System.Net.Http(Server)).
구성 요소
| 형식 | 역할 |
|---|---|
PasswordHasher |
a1$솔트$해시 형식 생성·검증(상수 시간 비교) |
SessionStore |
최대 8개·30분 RAM 세션 토큰 발급/검증/회수 |
TokenStore |
최대 4개·30일 RAM 리프레시 토큰(HMAC 해지로만 저장, 1회용 회전) |
LoginGuard |
위 셋 + 정적 API 키 + 5회 실패 시 60초 잠금을 묶은 파사드 |
[PublicEndpoint] |
인증 ON 시에도 통과시킬 핸들러 표시 마커(기본은 전부 보호) |
GuardedWebServer |
WebServer 파생 클래스. 라우팅 전에 LoginGuard를 연결해 fail-closed 인증을 적용 |
WebApi |
JSON/텍스트 응답·본문 읽기·JSON 이스케이프·보안 헤더 헬퍼 (WebApi.OkJson = {"ok":true} 상수) |
JsonWriter |
리플렉션 없는 수동 JSON 생성기. 따옴표·이스케이프·쉼표·중첩을 대신 관리 |
FormReader |
urlencoded 본문을 1회만 읽어 필드를 여러 개 파싱(이중 읽기 멈춤 방지) |
CsrfGuard |
커스텀 헤더 + Host 검사로 크로스사이트 POST·DNS rebinding 차단 |
AuthController |
/api/auth/* 표준 인증 엔드포인트 6종(status·login·logout·token·password·apikey). 훅과 메시지 필드로 앱에 맞춤 |
CredentialFile |
LoginGuard 해시·API 키를 h=/k= 파일에 원자적(load/save) 영속화 |
동작 원칙
- 자격 증명(비밀번호·API 키) 미설정 = 완전 개방: 둘 다 비어 있으면
CheckAccess는 항상Open을 반환합니다. 기존 자동화·스크립트를 깨뜨리지 않는 기본값입니다. 하나라도 설정되면 모든 엔드포인트가 보호됩니다(fail-closed). - 재부팅 = 세션 소멸: 토큰은 RAM에만 있어 기기가 재시작하면 로그인이 필요합니다. 해시와 API 키는 앱이 파일을 로드하면 그대로 유효합니다.
- 영속화는 선택 사항: 라이브러리는 자동으로 파일을 쓰지 않습니다.
원하면
CredentialFile.Load/Save로 해시·API 키를 한 줄에 파일과 동기화할 수 있습니다. - 선언적 접근 제어:
[PublicEndpoint]는 마커이며, 해석은GuardedWebServer가InvokeRoute오버라이드에서 매칭된 핸들러의 특성을 읽어 적용합니다. 특성이 없는 새 엔드포인트는 자동으로 보호됩니다(fail-closed). 거부 시401 unauthorized(잠금 시429)를 응답합니다. - 클라이언트 단절 흡수: 응답 도중 브라우저가 연결을 끊으면(fetch 취소·타임아웃)
쓰기에서
SocketException/IOException이 날 수 있습니다.GuardedWebServer.InvokeRoute와WebApi쓰기 경로가 이 계열만 잡아 연결을 닫고, 나머지 예외는 그대로 전파합니다. 덕분에 VS 디버거 첨부 중에도 요청 스레드가 앱 전체를 멈추지 않습니다. - 토큰 전달 경로:
GuardedWebServer.ReadSessionToken은 세션 헤더 →Authorization: Bearer→ 세션 쿠키 순으로 찾습니다. 헤더·쿠키 이름은 속성으로 바꿀 수 있습니다(기본값x-auth-session/x-auth-key/auth).CsrfGuard.Check(context, markerHeader, localAddress)의 마커 헤더 이름도 호스트가 결정하며, 차단 문구는CsrfGuard.BlockedMessage로 현지화할 수 있습니다.
해시 구현 주의 (nanoFramework)
PasswordHasher는 반드시 정적 HMACSHA256.HashData(key, data)만 사용합니다.
ESP32 nanoFramework에서 new HMACSHA256(key) + ComputeHash 인스턴스 경로는
키 스케줄링 결함으로 항상 0 출력이 되는 것을 실기기에서 확인했습니다
(솔트가 전부 0이 되어 로그인이 불가능해지는 증상으로 나타남).
순수 관리형 SHA-256 구현도 검증했으나 1000반복당 약 35초로 실사용 불가,
정적 경로는 0.3초 수준입니다.
토큰 발급 (Access/Refresh)
LoginGuard.TryLogin(password, out access, out refresh) 오버로드와 TryRefresh(...)로
OAuth의 password/refresh_token grant와 동일한 흐름을 만들 수 있습니다.
- 액세스 토큰은
SessionStore세션(30분)과 동일 객체라 쿠키·세션 헤더와 함께Authorization: Bearer <token>으로도 인정됩니다(파싱은 GuardedWebServer가 담당). - 리프레시 토큰은 128비트 랜덤 값이며 저장소에는 HMAC-SHA256 해지만 남습니다.
교환(
TryRefresh)마다 이전 토큰이 즉시 폐기되는 회전(rotation) 방식입니다. - 비밀번호가 바뀌면
PasswordHashsetter가 세션과 리프레시 토큰을 전량 회수합니다. - 리프레시 토큰도 RAM 전용이라 재부팅하면 전부 무효화됩니다.
엔트로피 주의
nanoFramework에는 하드웨어 난수 생성기가 노출되어 있지 않습니다.
SessionStore·TokenStore·솔트는 Guid.NewGuid+Environment.TickCount64를 HMAC-SHA256으로 확장해 만듭니다.
LAN 내 평문 HTTP용 인증에는 충분하지만, 인터넷 노출 환경에서는 TLS와 함께 사용하십시오.
검증
PC 미러(.csproj)로 PasswordHasher.Create/Verify 왕복과 LoginGuard 상태 전이를 확인할 수 있습니다.
사용 예
LoginGuard guard = new LoginGuard();
guard.Password = PasswordHasher.Create("s3cret!pass");
Type[] controllers = { typeof(MyController) };
GuardedWebServer server = new GuardedWebServer(80, controllers, guard)
{
SessionCookieName = "mysess"
};
server.CommandReceived += (s, e) => { /* 미라우팅 경로 처리 */ };
server.Start();
// 컨트롤러 핸들러 안에서
protected void Handle(WebServerEventArgs e)
{
if (CsrfGuard.Check(e.Context, "x-mymarker", Ethernet.GetLocalIP()))
return;
string pw = FormReader.Read(e.Context.Request, 768, "password");
string token;
if (guard.TryLogin(pw, out token) == LoginResult.Success)
{
server.SetSessionCookie(e.Context.Response, token);
WebApi.Json(e.Context.Response, 200, WebApi.OkJson);
}
else
{
WebApi.Error(e.Context.Response, 401, "wrong password");
}
}
JSON 응답 만들기 (JsonWriter)
JSON을 직접 만드는 일은 항상 번거롭습니다. "{\"ok\":true,\"name\":\"" + WebApi.JsonEscape(s) + "\"}" 식의
문자열 연결은 따옴표와 이스케이프를 수작업으로 맞추다 한 군데만 틀려도 응답 전체가 망가지고, 여러 조각을
Substring(1)로 잘어 붙이는 우회까지 부르기 쉽습니다. 자동 직렬화기는 nanoFramework의 리플렉션·힙 제약 때문에
의도적으로 제공하지 않습니다. 대신 리플렉션 없는 수동 생성기 JsonWriter가 그 몫을 대신합니다. 키와 값을
순서대로 적어 넣으면 따옴표·이스케이프·쉼표·중첩을 스스로 관리합니다.
JsonWriter w = new JsonWriter();
w.BeginObject()
.Prop("ok", true)
.Prop("uptime", uptimeSec) // 숫자
.Prop("authEnabled", guard.IsEnabled) // bool
.Prop("name", deviceName) // 문자열(자동 이스케이프)
.Prop("limits").BeginObject() // 중첩 객체
.Prop("nameMax", 30)
.EndObject()
.PropArr("settingsKeys", new string[]{ "deviceName", "pollMs" }) // 문자열 배열
.PropRaw("capabilities", "{\"points\":false}") // 이미 JSON인 조각은 그대로 병합
.EndObject();
WebApi.Json(e.Context.Response, 200, w.ToString());
Prop(name, 값)— 키·값 한 쌍. 값 타입에 따라Str/Num/Bool이 자동 선택됩니다.Prop(name)만 부르고BeginObject/BeginArray/Str/Num/Bool/Raw로 값을 잇는 체이닝도 됩니다(중첩·배열용).PropArr(name, items)— 문자열 배열 한 번에.PropRaw(name, json)— 다른 곳에서 만든 유효 JSON 조각 병합. 이스케이프 없이 그대로 들어갑니다.Null()은null, 빈 배열/객체는BeginArray().EndArray()처럼 바로 닫으면 됩니다.- 값이 아니라 구조가 고정된 단순 응답은
WebApi.OkJson상수({"ok":true})를 그대로 씁니다.
주의: Prop(name, long)과 Prop(name, int)가 모두 있어 정수 인자는 타입에 맞게 자동 선택되지만,
uptimeSec처럼 long 값은 Num/Prop에 그대로 넣으면 JSON 숫자로 나갑니다. MaxDepth(8)를 넘는
중첩은 InvalidOperationException을 던집니다.
인증 엔드포인트 열기 (AuthController)
로그인 화면(Pages\login.nf.*)이 이미 /api/auth/status·/api/auth/login을 호출하므로,
컨트롤러 배열에 typeof(AuthController)를 넣고 정적 필드만 배선하면 인증 API가 완성됩니다.
수동으로 핸들러를 쓰던 샘플/게이트웨이의 중복 코드는 이 한 클래스로 대체할 수 있습니다.
GuardedWebServer server = new GuardedWebServer(80,
new Type[] { typeof(MyController), typeof(AuthController), typeof(WebUiRoutes) }, guard);
server.Start();
AuthController.Server = server;
AuthController.CsrfMarker = "x-mymarker"; // status 응답의 csrfHeader로 전달됨
AuthController.StatusExtras = new AuthStatusExtrasWriter(MyApp.WriteExtras); // 상태에 앱 필드 병합(선택)
AuthController.Persist = new AuthCredentialPersist(() => { CredentialFile.Save(guard, Path); return null; });
AuthController.OnRequest = new AuthRequestObserver(MyApp.Observe); // 모든 인증 요청 관찰(선택)
AuthController.MsgBadPassword = "비밀번호가 올바르지 않습니다. 남은 시도 {0}회."; // 현지화(선택)
// 네트워크가 주소를 잡을 때마다:
AuthController.LocalAddress = ip; // CSRF Host 검사에 필수
| 엔드포인트 | 인증 | 설명 |
|---|---|---|
GET /api/auth/status |
불필요 | authEnabled/loggedIn/lockedOut/remaining/lockSec/csrfHeader + StatusExtras 병합 필드 |
POST /api/auth/login |
불필요(CSRF) | password 폼 필드 → 세션 쿠키 설정. 실패 401/429 |
POST /api/auth/logout |
불필요(CSRF) | 세션 회수 + 쿠키 삭제 |
POST /api/auth/token |
불필요(CSRF) | grant_type=password|refresh_token → Bearer/access/refresh JSON(회전 포함) |
POST /api/auth/password |
필요 | 비밀번호 교체(공백이면 해제). 성공 시 현재 브라우저는 새 세션으로 로그인 유지 |
POST /api/auth/apikey |
필요 | 정적 API 키 교체(공백이면 해제) |
password·apikey변경은Persist훅을 부르고, 훅이 오류 문자열을 반환하면500으로 응답합니다(메모리만 바뀜).- 6개 엔드포인트 진입점에서 항상
OnRequest훅이 먼저 불립니다(CSRF 검사 이전). 유휴 타이머 갱신·LocalAddress재동기화 같은 앱 고유의 관측 작업에 연결합니다. - 메시지는 정적 필드라 앱 시작에서 언어별로 바꿀 수 있습니다(기본값 영어).
{0}에는 남은 초/시도 횟수가 들어갑니다. Server·LocalAddress미설정 시 각각500(배선 오류 알림)·전 POST 차단으로 드러나 조용히 열리지 않습니다.
CredentialFile
h=<해시> / k=<키> 두 줄 형식 파일로 LoginGuard 자격 정보를 옮깁니다. 저장은 임시의존 이름(path.tmp)에
쓴 뒤 기존 파일을 지우고 rename하는 순서라, 전원 단절이 중간에 일어나도 반쪽(잘린) 파일이 남지 않습니다.
단, 정전 타이밍에 따라 파일이 잠시 없는 상태가 생길 수 있으며 이 경우 다음 저장이 새 파일로 만들어 기본값으로 돌아갑니다.
if (!CredentialFile.Load(guard, "I:\\device.auth"))
{
guard.SetPassword("first-run-default"); // 최초 실행 초기화
CredentialFile.Save(guard, "I:\\device.auth");
}
Save는 성공 시 null, 실패 시 사유를 돌려주어 AuthController.Persist 훅에 바로 연결할 수 있습니다.
실행 환경과 제한
MCU용 .NET nanoFramework 패키지입니다. 일반 .NET 앱용 패키지가 아닙니다. 설치되는 nanoFramework 시스템 패키지와 장치 펌웨어의 네이티브 어셈블리 버전이 호환되어야 합니다. UART·소켓·TLS 사용 시 해당 기능이 포함된 펌웨어가 필요합니다.
0.1.0-preview.7 평가용 사전 릴리스입니다. API 호환성과 공개 피드 지원 정책은 확정되지 않았습니다. 산업 현장 적용 검증이나 안전·적합성 인증을 마친 제품이 아닙니다. 통신 성공이 실제 설비 동작의 완료를 보장하지는 않습니다.
상세 문서와 라이선스
이 문서에는 패키지의 기능·사용 예·주요 제약을 함께 담았습니다. 추가 샘플과 개발 기록은 패키지 상세 문서와 라이브러리 그룹 안내에 있습니다. 소스 저장소에서 전체 코드를, 이슈 페이지에서 문제 제보와 논의를 확인할 수 있습니다. 저장소 빌드에는 .NET 10 SDK와 Visual Studio 2026의 nanoFramework 도구를 사용합니다. MCU에서는 일반 .NET 10이 아니라 nanoFramework가 실행됩니다.
MIT 라이선스이며, 외부 의존성에는 각각의 라이선스가 적용됩니다.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET Framework | net is compatible. |
-
- nanoFramework.CoreLibrary (= 1.17.11)
- nanoFramework.Runtime.Events (= 1.11.39)
- nanoFramework.Runtime.Native (= 1.7.11)
- nanoFramework.System.IO.FileSystem (= 1.1.96)
- nanoFramework.System.IO.Streams (= 1.1.96)
- nanoFramework.System.Net (= 1.11.66)
- nanoFramework.System.Net.Http.Server (= 1.5.214)
- nanoFramework.System.Security.Cryptography (= 1.0.43)
- nanoFramework.System.Text (= 1.3.42)
- nanoFramework.System.Threading (= 1.1.52)
- nanoFramework.WebServer (= 1.2.162)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.0-preview.7 | 45 | 11/17/2026 |
| 0.1.0-preview.6 | 55 | 11/16/2026 |
| 0.1.0-preview.5 | 54 | 11/16/2026 |
| 0.1.0-preview.4 | 52 | 11/16/2026 |
첫 평가용 사전 릴리스입니다. 이 패키지의 기능·설치 방법·사용 예와 주요 제약은 포함된 README에 정리했습니다. API 호환성과 공개 피드 지원 정책은 확정되지 않았으며 안전·적합성 인증을 마친 제품이 아닙니다.